saboteur 0.11.1 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74914fa96e0e644c7615013b6ad8a014c3c74b01e9b154931f2087fa0685dd31
-  data.tar.gz: 3265c82c7383a4ec2ce6355c009fc5816822e96334224e05a3cf6dac05404504
+  metadata.gz: 45635354d2b8067e2de9a11025677af615e3eb54da14dfcd26f0afbdcdd00073
+  data.tar.gz: 40a395d6909fb4bcec99596c6b34e4b40edf1b72c76b349ab25cb3ae44b48726
 SHA512:
-  metadata.gz: de0a4aa5db3d0403a46d9db2390fca263b9d7b433a9bbdb5d28049402c07d38ac75f2f68221bc4576ca3bc1a27c90c42aa7c62ba9f19d67eb6183507cfeef43b
-  data.tar.gz: 9d0286667bae0a37141efacd0547cb62d7185567ca8728f39be84902905f149f7d08f8eff2df07b2601083a8118a539d9d34fed06cfd47ec3840490c8ceb65a6
+  metadata.gz: 3f3dd155c87c3c6a45d1fd66a66cc5ec21d8c56dd5113dab2568cd07cc957ee2ba34bfc1b773cf4610aeee822e354bf36cc747418bcee24902365563f5f2b5c2
+  data.tar.gz: 23f785f27b3396a38195f44d6a418d819d6c7359fe34a8ec9f8422855206b53a5ebd634eb70d8c8d40cf622787a9795d99395950932a5870a2418d8651520aa9

data/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes are documented here. The format follows
 [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
+
+## [0.11.2] - 2026-10-22
+
+### Added
+
+- A full run warns when an ignore entry's subject never appears, so a
+  renamed or removed method can no longer kill the entry silently
+  (#1250, #1206).
+- Survivor gaps are labeled by kind instead of the blanket
+  `missing_test` label (#1246, #1153, #1064), and the README names
+  `tool_limit` and the gap kinds in the survivor triage labels (#1247).
+- The `explain` command prints a human-readable rationale for any
+  registry operator (#1251).
+- The HTML report lists survivors, timeouts and errors before killed
+  rows inside each file, keeping source order within each group
+  (#1253, #1233).
+- Survivor blocks consult the whole-suite coverage map, ending false
+  survivors from diff-scoped runs (#1252).
+
+### Changed
+
+- Output polish across the terminal, JSON and HTML reports: the flaky
+  check names why it exits 3, `doctor` prints its coverage line and a
+  run without a config says so (#1239); stubbed-test wording, the
+  timeout tally and the replay scope line are clearer (#1240);
+  selection messaging states nothing-to-test once and names the
+  `--since` scope on `--subject` misses (#1241); survivor blocks count
+  blocks, not mutants (#1242); the run opener and coverage-map counts
+  are pluralized (#1244); the clean screen labels its scope, hints at
+  the live reports and summarizes an empty diff (#1245).
+- Docs: the ignore list is named as the one way to accept a survivor,
+  the pre-1.0 policy for test selection and operator defaults is
+  stated, and the CLI-docs rule points at `docs/` rather than the
+  short README (#1248).
+
 ## [0.11.1] - 2026-10-22
 
 ### Added

data/README.md

@@ -80,7 +80,7 @@ tree refuses with exit 2 and points at the generator. Engine gem with
   assertion, 1 by a crash`), and an error-dominated run prints
   `Score: n/a` instead of a number you would misread.
 - 🔍 **Survivors you can act on.** Survivors group per statement with a
-  triage label (`likely_equivalent`, `arid`, `missing_test`) and their
+  triage label (`likely_equivalent`, `arid`, `tool_limit`, or a gap kind) and their
   covering tests - split into the tests that ran against the mutant and
   the ones that never did. `saboteur survivors` browses them read-only:
   one digest shows the full diff and the exact replay command.

data/lib/saboteur/cli/exit_status.rb

@@ -1,11 +1,15 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "flaky_exit"
+
 module Saboteur
   class CLI
     # How a finished run maps to an exit code and a recorded exit cause. Mixed
     # into the CLI, which supplies `config` and the `@err` stream.
     module ExitStatus
+      include FlakyExit
+
       private
 
       def exit_code(report)
@@ -15,7 +19,7 @@ module Saboteur
 
         return EXIT_TOOL if untested_partial?(report)
 
-        return EXIT_TOOL if unverifiable_scope?(report)
+        return EXIT_TOOL if unverifiable_scope?(report) || flaky_disagreement?(report)
 
         return EXIT_TOOL if mostly_errored?(report)
 
@@ -117,7 +121,7 @@ module Saboteur
         else
           if report.majority_errored?
             "errorMajority"
-          elsif unverifiable_review?(report) || unverifiable_unreachable?(report) ||
+          elsif unverifiable_review?(report) || unverifiable_unreachable?(report) || report.results.any?(&:flaky?) ||
                 (report.early_stop && report.score_breakdown.tested.zero?)
             "incomplete"
           else

data/lib/saboteur/cli/explain_command.rb

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "../help"
+require_relative "../reporter/palette"
+require_relative "../mutation_source/operator_explain"
+
+module Saboteur
+  class CLI
+    # Shared rendering for `saboteur explain <operator>` (#1097): the
+    # curated definition, a before/after example and survive/kill guidance
+    # for one operator, so a survivor's operator can be understood and
+    # targeted without leaving the terminal.
+    module ExplainCommand
+      private
+
+      def explain_command
+        name = @argv.shift
+        raise UsageError, "usage: saboteur explain <operator>" if name.nil?
+
+        entry = MutationSource::OperatorExplain.for(name)
+        if entry.nil?
+          @err.puts("saboteur: unknown operator: #{name}")
+          suggestion = MutationSource::OperatorRegistry.suggestion(name)
+          @err.puts("saboteur: #{suggestion}") unless suggestion.empty?
+          @err.puts("saboteur: operators: #{MutationSource::OperatorRegistry::DESCRIPTIONS.keys.join(', ')}")
+          return EXIT_USAGE
+        end
+
+        @out.puts(render_explain(entry, palette: Reporter::Palette.for(@out, mode: :auto)))
+        EXIT_OK
+      rescue UsageError => e
+        @err.puts("saboteur: #{e.message}")
+        EXIT_USAGE
+      end
+
+      def render_explain(entry, palette: Reporter::Palette.new(enabled: false))
+        original, replacement = entry.example.split(" -> ")
+        [
+          "#{palette.paint(:head, 'Operator:')} #{entry.name}",
+          "#{palette.paint(:head, 'Definition:')} #{entry.definition}",
+          palette.paint(:head, "Example:"),
+          "  #{palette.paint(:fail, "- #{original}")}",
+          "  #{palette.paint(:pass, "+ #{replacement}")}",
+          "#{palette.paint(:warn, 'Survives when:')} #{entry.survives}",
+          "#{palette.paint(:info, 'Kill it with:')} #{entry.kill}"
+        ].join("\n")
+      end
+    end
+  end
+end

data/lib/saboteur/cli/flaky_exit.rb

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # --flaky-check (#1167): a verdict that flipped on the reordered rerun is
+    # unverified, outside the score. The run was not stopped by a budget, so
+    # it is not exit 4, but it cannot go green either.
+    module FlakyExit
+      private
+
+      def flaky_disagreement?(report)
+        flaky = report.results.select(&:flaky?)
+        return false if flaky.empty?
+
+        @err.puts("saboteur: #{flaky.size} mutant#{'s' unless flaky.one?} changed verdict on the --flaky-check " \
+                  "reordered rerun (#{flaky.first(3).map(&:digest).join(', ')}), so they are unverified: " \
+                  "your tests depend on run order; fix that and run again")
+        true
+      end
+    end
+  end
+end

data/lib/saboteur/cli/run_command.rb

@@ -17,6 +17,18 @@ module Saboteur
 
       private
 
+      # A fresh checkout has no config file: say once that defaults are in
+      # use, and who writes one (#1172). Agent output stays machine-clean;
+      # there is no init command - the Rails generator writes the config.
+      def announce_missing_config_file(palette)
+        # @format, not agent_requested?: parse! has already eaten --format.
+        return if @format == "agent" || config.config_file_present
+
+        path = options[:config] || Config::FILE
+        notice = "saboteur: no #{path} - using defaults (Rails: bundle exec rails generate saboteur:install writes one)"
+        @err.puts(palette.paint(:dim, notice))
+      end
+
       def baseline_red?(error)
         error.message.to_s.match?(BASELINE_RED_MESSAGE)
       end
@@ -34,6 +46,7 @@ module Saboteur
         config.deprecation_warnings.each do |warning|
           @err.puts(Reporter::Notice.paint(notices, "saboteur: #{warning}"))
         end
+        announce_missing_config_file(notices)
 
         return preview if options[:list_operators] || options[:dry_run]
 

data/lib/saboteur/cli/run_output.rb

@@ -21,6 +21,16 @@ module Saboteur
         @out.puts "\nReports: #{names.join(', ')}"
       end
 
+      # The clean screen's scope label (#1173, #1174): --since, positional
+      # sources and --subject each name what the run covered.
+      def scope_label
+        parts = []
+        parts << "--since #{config['since']}" if config["since"]
+        parts.concat(@sources) if @sources
+        parts << "--subject #{config['subjects'].join(', ')}" if config["subjects"].any?
+        parts.empty? ? "whole project" : parts.join(", ")
+      end
+
       # Agent mode: stdout carries exactly one JSON payload. The target's own output (boot
       # files, hooks, spec loading, child processes) goes to stderr while the engine runs.
       # Descriptor 1 points at stderr for the block, so Kernel#puts, system and forked

data/lib/saboteur/cli/run_reporting.rb

@@ -22,7 +22,9 @@ module Saboteur
                                      overrides: config["palette"], threshold: config["threshold"],
                                      replay_command: survivor_replay_command(report, engine),
                                      all_mutants: options[:all_mutants] || false,
-                                     exit_code: code, previous_score: previous_score,
+                                     exit_code: code, previous_score: previous_score, scope: scope_label,
+                                     whole_suite_map: whole_suite_map_for(engine),
+                                     run_map: engine&.run_coverage_map,
                                      baseline_gate: (baseline_gate(report) if config["baseline"])).call(report)
         Reporter::Replay.new(@out).call(report) if options[:id]
         # The JSON carries the exit cause an outer harness trusts, so it is
@@ -38,6 +40,14 @@ module Saboteur
         code
       end
 
+      # No engine or no cache: no whole-suite map can exist, so the survivor
+      # block keeps its legacy covered-by line over an impossible build (review C1).
+      def whole_suite_map_for(engine)
+        return engine.whole_suite_coverage_map if engine&.whole_suite_map_lookup?
+
+        Reporter::SurvivorList::NO_WHOLE_SUITE_LOOKUP
+      end
+
       def agent_run(arguments)
         tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
         # The machine path is exempt from the noise diet: quiet_start: false
@@ -94,7 +104,8 @@ module Saboteur
       def survivor_replay_command(report, engine)
         lambda do |digest|
           tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
-          Reporter::Agent::Commands.replay(agent_provenance(report, tree, engine), digest, capped: false)
+          Reporter::Agent::Commands.replay(agent_provenance(report, tree, engine), digest, capped: false,
+                                                                                           report: report)
         end
       end
 

data/lib/saboteur/cli/survivors_command.rb

@@ -31,7 +31,7 @@ module Saboteur
           opts.on("--ranked", "Review-priority order: the report's ranked findings first")
           opts.on("--file SUBSTR", "Only survivors whose path contains SUBSTR")
           opts.on("--operator NAME", "Only survivors of operator NAME")
-          opts.on("--triage LABEL", "Only survivors classified LABEL (for example missing_test)")
+          opts.on("--triage LABEL", "Only survivors classified LABEL (for example boundary)")
           opts.on("--show DIGEST", "Diff, replay command and ignore template for one survivor")
         end
         options = {}

data/lib/saboteur/cli.rb

@@ -15,6 +15,7 @@ require_relative "cli/baseline_gate"
 require_relative "preview"
 require_relative "cli/run_reporting"
 require_relative "cli/survivors_command"
+require_relative "cli/explain_command"
 require_relative "cli/source_set"
 require_relative "cli/run_budget_options"
 require_relative "cli/shard_options"
@@ -44,6 +45,7 @@ module Saboteur
     include BaselineGate
     include RunReporting
     include SurvivorsCommand
+    include ExplainCommand
     include SourceSet
     include RunBudgetOptions
     include ShardOptions
@@ -103,6 +105,7 @@ module Saboteur
       when "run" then run_command
       when "baseline" then baseline
       when "survivors" then survivors_command
+      when "explain" then explain_command
       when "doctor" then doctor_command
       when "badge", "trend" then history_entry(command)
       when "version", "--version" then @out.puts(VERSION) || EXIT_OK

data/lib/saboteur/config.rb

@@ -146,7 +146,7 @@ module Saboteur
       end
 
       from_file = File.file?(path) ? ConfigFile.load(path) : {}
-      new(from_file.merge(stringify(overrides)), root: root)
+      new(from_file.merge(stringify(overrides)), root: root, config_file_present: File.file?(path))
     end
 
     def self.stringify(hash)
@@ -156,11 +156,16 @@ module Saboteur
     # Deprecations found while loading: printed by the CLI, never fatal.
     attr_reader :deprecation_warnings
 
-    def initialize(values = {}, root: Dir.pwd, explicit: nil)
+    # Whether the config file existed at load (#1172): the CLI says once
+    # when a run falls back to defaults because no file was there.
+    attr_reader :config_file_present
+
+    def initialize(values = {}, root: Dir.pwd, explicit: nil, config_file_present: true)
       # Retag the root losslessly: under a non-UTF-8 locale it arrives
       # locale-tagged, and every glob, join and expand below would mix
       # encodings with the UTF-8 patterns from the config file (#231).
       @root = Text.utf8_identity(File.expand_path(root))
+      @config_file_present = config_file_present
       unknown = values.keys - DEFAULTS.keys
       raise ConfigError, "unknown config key(s): #{unknown.join(', ')}" if unknown.any?
 

data/lib/saboteur/doctor.rb

@@ -76,7 +76,14 @@ module Saboteur
     # post-boot check re-reads the state without printing a second line.
     def check_coverage
       state = Coverage.state
-      @out.puts "Coverage: #{state}"
+      # "suspended" alone reads as a finding; it is the expected boot state
+      # - coverage is stopped while the app boots and starts for the map
+      # build (#1176). Any other state stays terse: verify_coverage raises.
+      if state == :suspended
+        @out.puts "Coverage: suspended during boot (saboteur starts it for the coverage map)"
+      else
+        @out.puts "Coverage: #{state}"
+      end
       verify_coverage(state)
     end
 

data/lib/saboteur/engine/coverage_store.rb

@@ -16,6 +16,9 @@ module Saboteur
       include CoverageParts
 
       CACHE_INPUTS = %w[integration require rspec_args rails tests coverage_recorder].freeze
+      # Names the freshest whole-suite map build; read as an untrusted hint:
+      # only a bare 64-hex key joins the cache dir (#427).
+      WHOLE_SUITE_POINTER = "whole-suite-map"
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
       LOG = "coverage-build.log"
       # RSpec rewrites this on every run (example_status_persistence_file_path),
@@ -31,7 +34,7 @@ module Saboteur
       TAIL_LINE_WIDTH = 300
 
       def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {}, load_methods: {},
-                     timeout_cap: nil, parts: 1)
+                     timeout_cap: nil, parts: 1, whole_suite_run: false)
         @config = config
         @parts = parts
         @integration = integration
@@ -41,6 +44,7 @@ module Saboteur
         @timeout_cap = timeout_cap
         @load_lines = load_lines
         @load_methods = load_methods
+        @whole_suite_run = whole_suite_run
         @root = File.realpath(config.root)
         @root_prefixes = Selection::CoverageMap.root_prefixes(config.root)
       end
@@ -58,14 +62,14 @@ module Saboteur
         path = cache_path(files)
         preloaded = LoadCoverage.preloaded_uninstrumented(files)
         cached = cached_map(files)
-        return refuse_empty_map(cached.with_preloaded(preloaded), files, preloaded) if cached
+        return serve_cached(path, cached, files, preloaded) if cached
 
         note = miss_note(files)
         @diagnostics.inform(note.message(scoped: !@config["tests"].empty?)) if @config["cache"]
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         map = fresh_map(files, note, preloaded)
         build_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
-        map.save(path)
+        persist_map(path, map)
         shadow(files, map, note, build_seconds) if shadow?
         note.save
         File.write(File.join(@config.path("cache_dir"), "preview.json"),
@@ -73,6 +77,31 @@ module Saboteur
         map
       end
 
+      # The map a whole-suite coverage build wrote on this tree, or nil.
+      # Survivor presentation consults it (presentation only, never
+      # selection): in a scoped run the run's own map holds only the specs
+      # the run loaded, so a "covered by" list from it can read as complete
+      # when another spec pins the behavior (false survivors by default,
+      # review C1). A full run keys its map with tests: [], so the lookup
+      # overrides a scoped run's --test value.
+      # The map this store's fetch produced (or served from cache): the
+      # run's own selection map, read by survivor presentation (review C1).
+      attr_reader :fetched_map
+
+      def whole_suite_map
+        return nil unless @config["cache"]
+
+        pointer = File.join(@config.path("cache_dir"), WHOLE_SUITE_POINTER)
+        return nil unless File.file?(pointer)
+
+        key = File.read(pointer, encoding: Encoding::UTF_8).strip
+        return nil unless key.match?(/\A[0-9a-f]{64}\z/)
+
+        Selection::CoverageMap.load(File.join(@config.path("cache_dir"), "coverage-#{key}.json"))
+      rescue SystemCallError, EncodingError
+        nil
+      end
+
       private
 
       # The partial map when it is on and safe, else the full build.
@@ -106,6 +135,28 @@ module Saboteur
         @cached_map ||= Selection::CoverageMap.load(cache_path(files))
       end
 
+      def serve_cached(path, cached, files, preloaded)
+        record_whole_suite_map(path)
+        refuse_empty_map(@fetched_map = cached.with_preloaded(preloaded), files, preloaded)
+      end
+
+      def persist_map(path, map)
+        map.save(path)
+        record_whole_suite_map(path)
+        @fetched_map = map
+      end
+
+      # The engine tells us when this run is a whole-suite build (no
+      # --since, no subjects, no explicit --test): remember the map key for
+      # later scoped runs, whose tree has usually drifted past the exact
+      # cache key already (review C1).
+      def record_whole_suite_map(path)
+        return unless @whole_suite_run
+
+        File.write(File.join(@config.path("cache_dir"), WHOLE_SUITE_POINTER),
+                   File.basename(path, ".json").delete_prefix("coverage-"), perm: 0o600)
+      end
+
       def cache_key(files)
         Selection::CoverageMap.cache_key(files: key_files(files), extra: key_inputs)
       end

data/lib/saboteur/engine/distribution.rb

@@ -110,7 +110,11 @@ module Saboteur
       # scheduler stopped mid-list at the budget deadline. Worker-level error
       # rows synthesize an error per candidate, so they never look truncated.
       def unverified_result?(result)
-        result.is_a?(MutantResult) && result.status == :unverified
+        result.is_a?(MutantResult) && result.status == :unverified && !result.flaky?
+      end
+
+      def budget_unverified_row?(result)
+        result["status"] == "unverified" && !MutantResult.flaky_reason?(result["reason"])
       end
 
       def record_unreached(rows, subjects, lists)
@@ -125,7 +129,7 @@ module Saboteur
           next unless row["results"] && !row["error"]
 
           @truncated << [subjects[i], lists[i].size - row["results"].size] if row["results"].size < lists[i].size
-          @unverified << subjects[i] if row["results"].any? { |result| result["status"] == "unverified" }
+          @unverified << subjects[i] if row["results"].any? { |result| budget_unverified_row?(result) }
         end
       end
 

data/lib/saboteur/engine/pipelines.rb

@@ -24,7 +24,9 @@ module Saboteur
                       mutate(subjects, files, integration, scope, ignore_list,
                              load_lines:, load_methods:)
                     end
-          @diagnostics.add_warnings(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
+          warnings = ignore_list.apply(results, subjects: subjects,
+                                                unscoped_digests: @unscoped_digests, full_run: unscoped_full_run?)
+          @diagnostics.add_warnings(warnings)
           build_report(results, subjects, scope, started)
         ensure
           # Cleanup runs however the call ends - a partway boot failure, no
@@ -54,7 +56,9 @@ module Saboteur
         files = config.included_files
         subjects, scope = select_subjects(files)
         results = subjects.empty? ? [] : mutate_external(subjects, scope, ignore_list)
-        @diagnostics.add_warnings(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
+        warnings = ignore_list.apply(results, subjects: subjects,
+                                              unscoped_digests: @unscoped_digests, full_run: unscoped_full_run?)
+        @diagnostics.add_warnings(warnings)
         build_report(results, subjects, scope, started)
       end
 
@@ -97,6 +101,14 @@ module Saboteur
         @diagnostics.warn(warning) if warning
       end
 
+      # "Full run" for ignore staleness (#1206): no --since diff, no --subject
+      # filter, and no narrowed include (explicit file arguments replace the
+      # configured include) - only then was every in-scope subject examined, so
+      # an entry whose subject never appears really points at gone code.
+      def unscoped_full_run?
+        !config["since"] && config["subjects"].empty? && config["include"] == Config::DEFAULTS["include"]
+      end
+
       def external_command? = !config["test_command"].to_s.empty?
 
       # The preflight's absolute monotonic deadline: its own

data/lib/saboteur/engine/scheduler.rb

@@ -352,7 +352,7 @@ module Saboteur
       def flaky_message(outcome, rerun)
         decisive = (outcome.failed_ids | rerun.failed_ids).first(3)
         named = decisive.empty? ? "" : " (decisive tests: #{decisive.join(', ')})"
-        "flaky verdict: first #{outcome.status}, then #{rerun.status} on a reordered confirmation " \
+        "#{MutantResult::FLAKY_PREFIX}: first #{outcome.status}, then #{rerun.status} on a reordered confirmation " \
           "run#{named} - the mutant is unverified, not #{outcome.status}"
       end
 

data/lib/saboteur/engine/selection_announcement.rb

@@ -11,12 +11,13 @@ module Saboteur
       private
 
       # A --since diff with no changed source file (a spec-only or docs-only
-      # change) yields zero subjects, so the suite never runs: say there is
-      # nothing to test rather than promise a whole-suite run that does not
-      # happen (#607).
+      # change) yields zero subjects, so the suite never runs: say why no
+      # spec was inferred rather than promise a whole-suite run that does not
+      # happen (#607). The conclusion itself is stated once, by the
+      # "--since <ref>: nothing to test - <reason>" outcome line (#1232).
       def selection_message(guess)
         if guess.changed.zero? && config["since"]
-          "inferred specs: no changed source file to infer a spec for, so there is nothing to test"
+          "inferred specs: no changed source file to infer a spec for"
         elsif guess.changed.zero?
           "inferred specs: no source file to infer a spec for, so the whole suite runs"
         elsif guess.specs.empty?

data/lib/saboteur/engine/subject_selection.rb

@@ -169,6 +169,11 @@ module Saboteur
           return missed.map { |pattern| missed_pattern_message(pattern) }.join("; ")
         end
 
+        if @config["since"]
+          return "--subject #{missed.join(', ')} matches no subject in the --since #{@config['since']} " \
+                 "diff scope (the scope limits the search to changed files; drop --since or pass --all)"
+        end
+
         "--subject #{missed.join(', ')} matches no subject (patterns are names like " \
           "Klass, Klass#meth or Klass.meth, not globs)"
       end
@@ -180,6 +185,11 @@ module Saboteur
         macro = attribute_macro_for(pattern)
         return "--subject #{pattern} is defined by #{macro} and has no body to mutate" if macro
 
+        if @config["since"]
+          return "--subject #{pattern} matches no subject in the --since #{@config['since']} diff scope " \
+                 "(the scope limits the search to changed files)"
+        end
+
         "fix the --subject pattern \"#{pattern}\": it matches no subject (patterns are names like " \
           "Klass, Klass#meth or Klass.meth, not globs)"
       end

data/lib/saboteur/engine.rb

@@ -4,6 +4,7 @@
 require "fileutils"
 require "json"
 require_relative "replay"
+require_relative "text"
 require_relative "mutation_source/hazard_guard"
 require_relative "baseline/run_evidence"
 require_relative "engine/early_stop_recording"
@@ -116,6 +117,24 @@ module Saboteur
       warnings + map.duplicate_keys(path).map { |key| "duplicate custom map key #{key}: Ruby keeps the last" }
     end
 
+    # The map this run selected tests from: survivor presentation compares
+    # it against the cached whole-suite map (review C1).
+    def run_coverage_map
+      @coverage_store&.fetched_map
+    end
+
+    # The cached whole-suite map on this tree, for survivor presentation
+    # in scoped runs; nil when caching is off or no full build ran (review C1).
+    def whole_suite_coverage_map
+      @coverage_store&.whole_suite_map
+    end
+
+    # False when caching is off, where no coverage build can ever leave a
+    # whole-suite map to consult, so advising one would be wrong (review C1).
+    def whole_suite_map_lookup?
+      config["cache"] ? true : false
+    end
+
     private
 
     # Inferred test selection, the default since 0.7.0: scope the run to the
@@ -312,16 +331,27 @@ module Saboteur
                                     tests: map.tests.size, cached: @map_cached)
         @diagnostics.quiet_inference(@quiet_spec_count)
       else
-        @diagnostics.inform("#{subjects.size} subjects, #{map.tests.size} tests in coverage map")
+        @diagnostics.inform("#{Text.counted(subjects.size, 'subject')}, " \
+                            "#{Text.counted(map.tests.size, 'test')} in coverage map")
       end
       ThreadWarnings.warn(@diagnostics, rails: config["rails"])
     end
 
+    # This run's map is the whole-suite map only when nothing scoped it:
+    # no --since, no subjects, and tests either unset or inferred over every
+    # included file (never an explicit --test list) (review C1).
+    def whole_suite_run?
+      config["since"].nil? && config["subjects"].empty? &&
+        (config["tests"].empty? || !@guessed_tests.nil?)
+    end
+
     def coverage_store(integration, load_lines, load_methods = {})
-      CoverageStore.new(config: config, integration: integration, hooks: hooks, load_lines:, load_methods:,
-                        supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics,
-                        timeout_cap: method(:budget_capped_timeout),
-                        parts: config["coverage_parts"])
+      @coverage_store ||=
+        CoverageStore.new(config: config, integration: integration, hooks: hooks, load_lines:, load_methods:,
+                          whole_suite_run: whole_suite_run?,
+                          supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics,
+                          timeout_cap: method(:budget_capped_timeout),
+                          parts: config["coverage_parts"])
     end
 
     def check_baseline(integration, full_passes)

data/lib/saboteur/help.rb

@@ -152,6 +152,17 @@ module Saboteur
                    ["Diff, replay command and ignore template for one mutant",
                     "saboteur survivors .saboteur/report.json --show 1a2b3c4d5e6f7a8b"]]
       ),
+      Command.new(
+        name: "explain",
+        summary: "Explain one mutation operator: definition, example and kill guidance",
+        description: "Prints what one operator does, a before/after example of the mutation, the test " \
+                     "shapes that let it survive, and the assertion that kills it. Covers every operator " \
+                     "the registry can emit.",
+        takes_options: false,
+        exit_codes: { 0 => "Explanation printed.",
+                      2 => "Unknown or missing operator name; the valid names are listed." },
+        examples: [["Why did this mutant survive?", "saboteur explain operand_replacement"]]
+      ),
       Command.new(
         name: "badge",
         summary: "Print a shields.io endpoint badge over the opt-in score history",