saboteur 0.9.0 → 0.11.0

data/lib/saboteur/cli/baseline_gate.rb

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "digest"
+
+module Saboteur
+  class CLI
+    # The `saboteur run --baseline PATH` gate: loading the accepted baseline
+    # (fail fast, before the suite boots) and mapping the comparison to the
+    # run's exit code. Mixed into the CLI, which supplies `config`.
+    module BaselineGate
+      private
+
+      # The --baseline comparison replaces the ordinary quality-gate verdict.
+      def exit_code(report) = config["baseline"] ? baseline_verdict(report) : super
+
+      # --baseline: the comparison against the accepted baseline is the
+      # verdict. Accepted legacy survivors no longer fail the run; new
+      # survivors or a score drop beyond --epsilon do (exit 1). An
+      # incompatible baseline is a usage error; an incomplete comparison
+      # means the run's own evidence cannot judge it (exit 3).
+      def baseline_verdict(report)
+        gate = baseline_gate(report)
+        raise ConfigError, gate.comparison.issues.join("; ") if gate.incompatible?
+        return EXIT_TOOL if gate.incomplete?
+
+        gate.failed? ? EXIT_SURVIVORS : EXIT_OK
+      end
+
+      def baseline_gate(report)
+        @baseline_gate ||= begin
+          path = config["baseline"]
+          if Digest::SHA256.file(path).hexdigest != @baseline_digest
+            raise ConfigError, "baseline changed during the run"
+          end
+
+          Baseline::RunGate.build(manifest: baseline_manifest, report: report, epsilon: config["epsilon"] || 0.0)
+        end
+      end
+
+      # The accepted baseline at config["baseline"], loaded once (and before
+      # the suite boots) so a missing or corrupt file fails fast as a usage
+      # error naming the fix.
+      def baseline_manifest
+        return @baseline_manifest if @baseline_manifest
+
+        path = config["baseline"]
+        raise UsageError, "--baseline file not found: #{path} - run `saboteur baseline propose` first" unless
+          File.exist?(path)
+
+        @baseline_manifest, @baseline_digest = Baseline::Loader.call(path)
+        @baseline_manifest
+      rescue ConfigError => e
+        raise UsageError, "#{e.message} - run `saboteur baseline propose` first"
+      end
+    end
+  end
+end

data/lib/saboteur/cli/error_cause.rb

@@ -15,6 +15,22 @@ module Saboteur
 
       LIMIT = 200
 
+      # The machine cause and the one-line human reason for the two exits no
+      # report can describe, because the run never produced one. The verdict
+      # line names the reason for a nonzero exit; the report-driven codes get
+      # theirs from the terminal summary's verdict line.
+      # Keyed by exit code. Literals for EXIT_BASELINE_RED and EXIT_CRASH:
+      # this file loads before the CLI defines them; the cause pins spec
+      # asserts the keys are those two constants.
+      CAUSE_LINES = {
+        5 => ["baselineRed", "baseline suite red: fix your tests first"],
+        70 => ["crash", "internal crash (a saboteur bug, never your code)"]
+      }.freeze
+
+      def self.cause(code) = CAUSE_LINES.fetch(code).first
+
+      def self.verdict_line(code) = "exit #{code} - #{CAUSE_LINES.fetch(code).last}"
+
       # "" when no result carries a reason.
       def self.line(errored)
         reasons = errored.filter_map { |result| first_line(result.reason) }.reject(&:empty?)

data/lib/saboteur/cli/exit_status.rb

@@ -8,22 +8,11 @@ module Saboteur
     module ExitStatus
       private
 
-      # Last resort: a bug must not escape as a bare stack trace and an accidental exit 1.
-      def internal_error(error)
-        CrashReport.call(error, verbose: @verbose, agent: agent?, err: @err, out: @out, log_path: crash_log_path)
-      end
-
-      # The crash log lives with the other run state. A broken config (or a
-      # nil cache_dir) must not swallow the crash report itself: no log.
-      def crash_log_path
-        config.path("cache_dir")&.then { |dir| File.join(dir, CrashReport::LOG_NAME) }
-      rescue StandardError
-        nil
-      end
-
       def exit_code(report)
         return EXIT_BUDGET if budget_exhausted?(report)
 
+        return EXIT_OK if ignore_empty_diff?(report)
+
         return EXIT_TOOL if untested_partial?(report)
 
         return EXIT_TOOL if unverifiable_scope?(report)
@@ -36,6 +25,17 @@ module Saboteur
         gates.failed?(report, @err, record_cause: !quality_failed) || quality_failed ? EXIT_SURVIVORS : EXIT_OK
       end
 
+      # --ignore-empty: a --since diff that selected no mutants exits 0 with
+      # a note; suppressed, omitted or undiscovered mutants still gate.
+      def ignore_empty_diff?(report)
+        return false unless config["ignore_empty"] && config["since"] && report.results.empty?
+        return false unless report.omissions.empty? && report.inline_suppressions.empty? &&
+                            report.discovery_failures.empty?
+
+        @err.puts("saboteur: no mutants in the diff - nothing to gate (--ignore-empty)")
+        true
+      end
+
       # A spent --max-duration budget exits 4 on its own, before the gates:
       # the run is partial by design, and --max-duration-ok opts back into
       # the plain verdict.
@@ -112,6 +112,7 @@ module Saboteur
         when EXIT_OK then "ok"
         when EXIT_BUDGET then "budgetExhausted"
         when EXIT_SURVIVORS then survivors_cause(report)
+        when EXIT_BASELINE_RED, EXIT_CRASH then ErrorCause.cause(code)
         else
           if report.majority_errored?
             "errorMajority"

data/lib/saboteur/cli/failure_output.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../reporter/palette"
+
 module Saboteur
   class CLI
     # Where a failed command speaks: stderr for people, and in agent mode the
@@ -8,6 +10,20 @@ module Saboteur
     module FailureOutput
       private
 
+      # Last resort: a bug must not escape as a bare stack trace and an accidental exit 1.
+      def internal_error(error)
+        CrashReport.call(error, verbose: @verbose, agent: agent?, err: @err, out: @out,
+                                log_path: crash_log_path, color: @color || :auto)
+      end
+
+      # The crash log lives with the other run state. A broken config (or a
+      # nil cache_dir) must not swallow the crash report itself: no log.
+      def crash_log_path
+        config.path("cache_dir")&.then { |dir| File.join(dir, CrashReport::LOG_NAME) }
+      rescue StandardError
+        nil
+      end
+
       def usage_error(message = nil)
         @err.puts(message) if message
         @err.puts(USAGE)
@@ -28,8 +44,15 @@ module Saboteur
       def report_failure(error, exit_code)
         message = Text.display_safe_lines(error.message)
         @err.puts("saboteur: #{message}")
+        @err.puts(verdict_line(EXIT_BASELINE_RED)) if exit_code == EXIT_BASELINE_RED
         agent_failure(message, exit_code)
       end
+
+      # The terminal verdict names the reason for a nonzero exit. Painted
+      # red under the same colour rules as the report.
+      def verdict_line(code)
+        Reporter::Palette.for(@err, mode: @color || :auto).paint(:fail, ErrorCause.verdict_line(code))
+      end
     end
   end
 end

data/lib/saboteur/cli/output_options.rb

@@ -8,19 +8,41 @@ module Saboteur
       private
 
       def define_output_options(opts)
+        define_report_destination_options(opts)
+        define_text_report_options(opts)
+      end
+
+      # Report destinations and the format switch.
+      def define_report_destination_options(opts)
         opts.on("--score-history PATH", "Append score history JSONL (opt-in)") { |v| set(:score_history, v) }
         opts.on("--json PATH", "Stryker JSON report path") { |v| set(:json_report, v) }
         opts.on("--html PATH", "Self-contained HTML report path") { |v| set(:html_report, v) }
         opts.on("--format FORMAT", %w[text agent json], "text, agent or json (--dry-run inventory)") { |v| @format = v }
         opts.on("--agent", "Same as --format agent") { @format = "agent" }
+      end
+
+      # Flags that shape the text report. Kept under the per-method mutant cap
+      # by the destination/text split above.
+      def define_text_report_options(opts)
         opts.on("--verbose", "Text report: also print score split, timings and kill causes;",
                 "a crash prints its backtrace") do
           @verbose = true
           set(:verbose, true)
         end
-        opts.on("--[no-]color", "Colour the text report (default: on for a terminal unless NO_COLOR is set)") do |v|
-          @color = v ? :always : :never
+        opts.on("--color [MODE]", %w[always never auto],
+                "Colour the text report: always, never or auto (default: auto)") do |v|
+          @color = (v || :always).to_sym
+        end
+
+        # PR6: CI and pre-push output - the findings and the verdict only.
+        opts.on("--quiet", "Text report: print only the findings and the verdict;",
+                "no effect with --format json/agent; ignores --all-mutants") do
+          @quiet = true
+          set(:quiet, true)
         end
+        opts.on("--all-mutants", "Text report: list every survived mutant;",
+                "default: one finding per statement, with the label mix") { set(:all_mutants, true) }
+        opts.on("--no-color", "Deprecated alias for --color=never") { @color = :never }
       end
     end
   end

data/lib/saboteur/cli/run_budget_options.rb

@@ -22,6 +22,12 @@ module Saboteur
                                            "coverage map spend it too") do |v|
           set(:max_duration, parse_duration(v))
         end
+        opts.on("--baseline PATH", "Gate the run on an accepted baseline: only new survivors or a score " \
+                                   "drop beyond --epsilon fail (propose one with: saboteur baseline propose)") do |v|
+          set(:baseline, v)
+        end
+        opts.on("--epsilon POINTS", Float, "With --baseline: allowed score drop in percentage points " \
+                                           "(default 0: any drop fails)") { |v| set(:epsilon, v) }
         opts.on("--[no-]max-duration-ok", "An exhausted --max-duration budget does not fail the run") do |v|
           set(:max_duration_ok, v)
         end

data/lib/saboteur/cli/run_command.rb

@@ -6,8 +6,21 @@ module Saboteur
     # `saboteur run`: parse, validate, then preview or execute (#334).
     # Extracted from CLI by command.
     module RunCommand
+      # The baseline-red shapes the engine raises as Saboteur::Error when the
+      # unchanged suite itself fails: the user's tests are broken, so no
+      # mutant was ever judged. These route to EXIT_BASELINE_RED; every other
+      # deliberate raise keeps EXIT_TOOL.
+      BASELINE_RED_MESSAGE = /\A#{Regexp.union(
+        'baseline check ', 'baseline has no tests', 'the unchanged suite failed',
+        'the test command fails on the unchanged tree'
+      )}/
+
       private
 
+      def baseline_red?(error)
+        error.message.to_s.match?(BASELINE_RED_MESSAGE)
+      end
+
       def run_command = help_requested? ? show_help("run") : run
 
       def run
@@ -26,7 +39,7 @@ module Saboteur
       rescue ConfigError => e
         report_failure(e, EXIT_USAGE)
       rescue Error => e
-        report_failure(e, EXIT_TOOL)
+        report_failure(e, baseline_red?(e) ? EXIT_BASELINE_RED : EXIT_TOOL)
       end
     end
   end

data/lib/saboteur/cli/run_reporting.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "../reporter/score_history"
+require_relative "../reporter/history_reader"
 require_relative "../reporter/history_paths"
 
 module Saboteur
@@ -12,10 +13,18 @@ module Saboteur
 
       def text_run(report, engine)
         @err.puts
-        Reporter::Terminal.new(@out, verbose: @verbose || false, color: @color || :auto,
-                                     replay_command: survivor_replay_command(report, engine)).call(report)
-        Reporter::Replay.new(@out).call(report) if options[:id]
+        # Classify before printing: the terminal's closing verdict line names
+        # the exit and its reason, so the code must be known up front. The
+        # gate and skip notes exit_code writes to @err now precede the
+        # report instead of following it.
         code = exit_code(report)
+        Reporter::Terminal.new(@out, verbose: @verbose || false, quiet: @quiet || false, color: @color || :auto,
+                                     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,
+                                     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
         # the completion evidence for the whole run: write it only after
         # every other fallible reporting stage, or a late failure would
@@ -31,7 +40,9 @@ module Saboteur
 
       def agent_run(arguments)
         tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
-        engine = Engine.new(config, **arguments)
+        # The machine path is exempt from the noise diet: quiet_start: false
+        # keeps agent stderr byte-identical to the pre-diet default output.
+        engine = Engine.new(config, **arguments, quiet_start: false)
         report = stdout_on_stderr { engine.call }
         payload = Reporter::Agent.call(report, agent_provenance(report, tree, engine))
         rendered = Reporter::Agent.render(payload)
@@ -49,8 +60,13 @@ module Saboteur
 
       def execute_run
         validate_history
-        arguments = { err: @err }
+        # One palette per stream: stdout and stderr detect colour on their
+        # own, so a forced terminal report still leaves piped progress plain.
+        arguments = { err: @err,
+                      palette: Reporter::Palette.for(@err, mode: @color || :auto, overrides: config["palette"]) }
         arguments[:digest] = options[:id] if options[:id]
+        arguments[:capture_evidence] = true if config["baseline"]
+        arguments[:evidence_files] = [config["baseline"]] if config["baseline"]
         return agent_run(arguments) if agent?
 
         # Text mode only: the engine prints a per-subject marks line when
@@ -63,6 +79,18 @@ module Saboteur
       # selection options, assembled by the same code that writes the agent
       # follow-ups, so the user never reassembles them by hand (#261).
       # Computed lazily: only a run with survivors asks for it.
+      # The headline's delta: the covered score of the last history record.
+      # The history is auxiliary evidence (#296): anything unreadable simply
+      # means no delta, since validate_history reports real corruption.
+      def previous_score
+        path = config.path("score_history")
+        return unless path && File.exist?(path)
+
+        Reporter::HistoryReader.read(path).last&.fetch("coveredScore", nil)
+      rescue Error
+        nil
+      end
+
       def survivor_replay_command(report, engine)
         lambda do |digest|
           tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
@@ -126,7 +154,7 @@ module Saboteur
         return unless path
 
         tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
-        scope = config.selection_settings.except(*Config::OUTPUT_KEYS)
+        scope = config.selection_settings.except(*Config::OUTPUT_KEYS, *Config::PRESENTATION_KEYS)
         # Recording is an auxiliary artifact: when the file cannot be
         # written - read-only tree inside a sandboxed child (#296) - warn
         # and let the run exit by its results instead of failing as a tool

data/lib/saboteur/cli/run_validation.rb

@@ -36,19 +36,52 @@ module Saboteur
       def validate_run_options
         reject_format_conflicts
         validate_shard_options
+        raise UsageError, "--ignore-empty applies to --since runs" if config["ignore_empty"] && !config["since"]
+
+        validate_baseline_options
+
         Selection::GitDiff.verify_ref!(config["since"], root: config.root) if config["since"]
       end
 
+      # The run gate needs fresh whole-scope execution evidence, so it
+      # refuses every flag the evidence capture rejects, up front. A missing
+      # or corrupt baseline file is a usage error before the suite boots.
+      def validate_baseline_options
+        raise UsageError, "--epsilon applies with --baseline" if config["epsilon"] && !config["baseline"]
+        if config["epsilon"] && !(0.0..100.0).cover?(config["epsilon"])
+          raise UsageError, "--epsilon must be between 0 and 100"
+        end
+        return unless config["baseline"]
+
+        conflicts = %w[since incremental threshold resume shard].select { |key| config[key] }
+        conflicts << "id" if options[:id]
+        unless conflicts.empty?
+          flags = conflicts.map { |key| "--#{key}" }.join(", ")
+          raise UsageError, "--baseline cannot be combined with #{flags}"
+        end
+        baseline_manifest
+      end
+
       # Agent mode allows no score gates (one strict exit 0); the json inventory is --dry-run planning only.
       def reject_format_conflicts
-        if agent? && (config["threshold"] || gates.any?)
-          raise UsageError, "#{config['threshold'] ? '--threshold' : gates.agent_option_name} " \
-                            "cannot be combined with --agent"
+        # --quiet prints only the findings and the verdict; --verbose adds
+        # the debug statistics. One output cannot be both.
+        raise UsageError, "--quiet cannot be combined with --verbose" if options[:quiet] && options[:verbose]
+
+        if agent? && (config["threshold"] || config["baseline"] || gates.any?)
+          raise UsageError, "#{agent_gate_name} cannot be combined with --agent"
         end
         return unless @format == "json" && !options[:dry_run]
 
         raise UsageError, "--format json is the --dry-run mutant inventory; a run summary is --format agent"
       end
+
+      def agent_gate_name
+        return "--threshold" if config["threshold"]
+        return "--baseline" if config["baseline"]
+
+        gates.agent_option_name
+      end
     end
   end
 end

data/lib/saboteur/cli/selection_options.rb

@@ -22,6 +22,8 @@ module Saboteur
         opts.on("--id DIGEST", "Replay exactly one current mutant by its full digest") { |v| set(:id, v) }
         opts.on("--shard K/N", "Run one of N deterministic candidate shards (for example 1/4)") { |v| set(:shard, v) }
         opts.on("--since REF", "Only mutate subjects changed since git REF") { |v| options[:since] = v }
+        opts.on("--ignore-empty", "A --since diff that selects no mutants exits 0 with a note instead of " \
+                                  "failing a score gate") { set(:ignore_empty, true) }
         flaky_desc = "Confirm a fresh verdict (survivors, decisive) with one reordered rerun"
         opts.on("--flaky-check MODE", %w[off survivors decisive], flaky_desc) { |v| set(:flaky_check, v) }
         opts.on("--subject EXPR", "Klass#meth, Klass.meth or a namespace; repeatable") { |v| add_subject(v) }

data/lib/saboteur/cli.rb

@@ -8,8 +8,10 @@ require_relative "doctor"
 require_relative "help"
 require_relative "reporter/replay"
 require_relative "baseline/command"
+require_relative "baseline/run_gate"
 require_relative "cli/error_cause"
 require_relative "cli/exit_status"
+require_relative "cli/baseline_gate"
 require_relative "preview"
 require_relative "cli/run_reporting"
 require_relative "cli/survivors_command"
@@ -39,6 +41,7 @@ module Saboteur
   class CLI
     include Baseline::Command
     include ExitStatus
+    include BaselineGate
     include RunReporting
     include SurvivorsCommand
     include SourceSet
@@ -73,6 +76,8 @@ module Saboteur
     EXIT_USAGE = 2
     EXIT_TOOL = 3
     EXIT_BUDGET = 4
+    EXIT_BASELINE_RED = 5
+    EXIT_CRASH = 70
     class UsageError < ConfigError; end
 
     attr_reader :options
@@ -131,7 +136,7 @@ module Saboteur
 
     def agent_requested? = self.class.agent_requested?(@argv)
 
-    def overrides = options.except(:config, :id, :suite, :list_operators, :dry_run)
+    def overrides = options.except(:config, :id, :suite, :list_operators, :dry_run, :all_mutants, :quiet)
 
     def add_subject(expr) = (options[:subjects] ||= []) << expr
 

data/lib/saboteur/config.rb

@@ -22,6 +22,11 @@ module Saboteur
     # out of the run fingerprint, baseline evidence and score-history scope.
     OUTPUT_KEYS = %w[cache_dir json_report html_report score_history resume].freeze
 
+    # Presentation-only settings: like OUTPUT_KEYS they never enter the run
+    # fingerprint, baseline evidence or score-history scope, but they are
+    # not paths.
+    PRESENTATION_KEYS = %w[palette].freeze
+
     DEFAULTS = {
       "integration" => "rspec",
       "require" => [],
@@ -77,6 +82,9 @@ module Saboteur
       # cache miss and compares it with the full map, which the run still uses.
       # "use" uses the partial map when it is safe and builds the full map otherwise.
       "partial_coverage" => "off",
+      # Total seconds survivor confirmation may spend per run when
+      # partial_coverage=use (#1063); the per-survivor spec cap is a constant.
+      "confirmation_budget" => 300.0,
       # coverage (default) reads Coverage around every test; trace gets lines and
       # methods from a TracePoint and reads branches once per spec file (#725).
       "coverage_recorder" => "coverage",
@@ -95,6 +103,9 @@ module Saboteur
       "coverage_parts" => 1,
       "max_duration" => nil,
       "max_duration_ok" => false,
+      "ignore_empty" => false,
+      "baseline" => nil,
+      "epsilon" => nil,
       "tests" => [],
       "test_command" => nil,
       "fingerprint_extra" => [],
@@ -103,12 +114,15 @@ module Saboteur
       "max_errors" => nil,
       # --verbose also lands here, so boot-time output filters (the rspec
       # load-error report, #608) can keep their raw text behind the flag.
-      "verbose" => false
+      "verbose" => false,
+      # Text-report colour overrides: token -> ANSI colour name, validated
+      # against Reporter::Palette. Presentation only, never fingerprinted.
+      "palette" => {}
     }.freeze
 
     INTEGER_KEYS = %w[jobs max_memory_mb max_processes max_mutants_per_method seed baseline_passes
                       coverage_parts].freeze
-    FLOAT_KEYS = %w[timeout_factor timeout_min baseline_timeout coverage_timeout].freeze
+    FLOAT_KEYS = %w[timeout_factor timeout_min baseline_timeout coverage_timeout confirmation_budget].freeze
     STRING_KEYS = %w[test_selection partial_coverage coverage_recorder].freeze
     NILABLE_FLOAT_KEYS = %w[threshold max_duration].freeze
     THRESHOLD_RANGE = (0.0..100.0)
@@ -321,6 +335,7 @@ module Saboteur
     end
 
     def validate_modes!
+      validate_palette!
       validate_fail_fast!
       validate_matrix!
       validate_resume!
@@ -427,6 +442,12 @@ module Saboteur
       raise ConfigError, 'test_command runs the command unsandboxed, so sandbox "strict" cannot be honored'
     end
 
+    def validate_palette!
+      Reporter::Palette.validate_overrides!(self["palette"])
+    rescue ArgumentError => e
+      raise ConfigError, e.message
+    end
+
     def validate_reeval!
       raise ConfigError, "reeval must be one of: #{Execution::Reevaluator::STRATEGIES.join(', ')}" unless
         Execution::Reevaluator::STRATEGIES.include?(self["reeval"].to_s)

data/lib/saboteur/crash_report.rb

@@ -6,18 +6,26 @@ require "json"
 require "tmpdir"
 require "pathname"
 
+require_relative "reporter/palette"
+
 module Saboteur
   # Last-resort crash reporting, shared by the CLI's StandardError rescue
   # and the exe-level wrapper: one bounded line on stderr, the full
   # backtrace in a log file the line names, the backtrace on stderr with
   # --verbose, and the same failure as agent JSON when an agent listens.
-  # Always returns EXIT_TOOL.
+  # Always returns EXIT_CRASH (70): a crash is a saboteur bug, never a
+  # check the user can fix.
   module CrashReport
     ISSUES_URL = "https://github.com/vamsipavanmahesh/saboteur/issues"
 
-    # Same value as CLI::EXIT_TOOL, kept local so the reporter still works
+    # Same value as CLI::EXIT_CRASH, kept local so the reporter still works
     # when the CLI itself never finished loading.
-    EXIT_TOOL = 3
+    EXIT_CRASH = 70
+
+    # The crash cause's verdict line, kept in sync with
+    # CLI::ErrorCause::CAUSE_LINES["crash"] by the cause pins: the reporter
+    # cannot load the CLI's vocabulary when the CLI itself never loaded.
+    VERDICT_LINE = "exit 70 - internal crash (a saboteur bug, never your code)"
 
     # The crash log's file name under the run's cache dir; the runner reads
     # it back to explain a nested run's crash in the failure detail (#296).
@@ -25,15 +33,16 @@ module Saboteur
 
     module_function
 
-    def call(error, verbose:, agent:, err:, out:, log_path: nil)
+    def call(error, verbose:, agent:, err:, out:, log_path: nil, color: :auto)
       summary = "internal error (#{error.class}: #{one_line(error.message)})"
       line = "saboteur: #{summary} - please report it: #{ISSUES_URL}"
       written = write_log(log_path, error)
       line = "#{line}; full backtrace: #{display_path(written)}" if written
       err.puts(line)
+      err.puts(Reporter::Palette.for(err, mode: color).paint(:fail, VERDICT_LINE))
       err.puts(full_text(error)) if verbose
       out.print(agent_json(summary)) if agent
-      EXIT_TOOL
+      EXIT_CRASH
     end
 
     # A crash message can span lines or carry bytes that are invalid in
@@ -59,9 +68,9 @@ module Saboteur
     def agent_json(summary)
       payload =
         if defined?(Reporter::Agent)
-          Reporter::Agent.failure(summary, EXIT_TOOL)
+          Reporter::Agent.failure(summary, EXIT_CRASH)
         else
-          { version: 1, status: "error", verdict: "tool_failure", exitCode: EXIT_TOOL,
+          { version: 1, status: "error", verdict: "tool_failure", exitCode: EXIT_CRASH,
             message: summary, next: { help: "saboteur help run" } }
         end
       "#{JSON.pretty_generate(payload)}\n"

data/lib/saboteur/engine/baseline_guard.rb

@@ -46,7 +46,7 @@ module Saboteur
           expected.empty?
 
         passes = @config["baseline_passes"]
-        @diagnostics.inform(announce(passes))
+        @diagnostics.detail(announce(passes))
         previous = nil
         passes.times do |index|
           break if budget_spent?(index)
@@ -114,7 +114,7 @@ module Saboteur
         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 " \
+        @diagnostics.detail("baseline check #{number} took #{elapsed} s; about #{elapsed * total} s left for " \
                             "#{work.join(' and ')} at that rate")
       end
 

data/lib/saboteur/engine/coverage_partial.rb

@@ -12,12 +12,19 @@ module Saboteur
     # shadow helpers it shares (shadow_invalidation, shadow_rerun,
     # shadow_clean).
     module CoveragePartial
+      # The full opt-in predicate, factored out for survivor confirmation
+      # (#1063): partial coverage only applies to a cached, unscoped,
+      # single-part run.
+      def self.use?(config, parts)
+        config["partial_coverage"] == "use" && config["cache"] && config["tests"].empty? && parts == 1
+      end
+
       private
 
       # Same preconditions as the shadow run: a scoped or parted map is not
       # what a partial rebuild starts from.
       def partial_use?
-        @config["partial_coverage"] == "use" && @config["cache"] && @config["tests"].empty? && @parts == 1
+        CoveragePartial.use?(@config, @parts)
       end
 
       def partial_map(files, note, preloaded)

data/lib/saboteur/engine/coverage_store.rb

@@ -393,11 +393,10 @@ module Saboteur
 
       def preloaded_message(files)
         names = Text.name_list(files.map { |file| file.delete_prefix("#{@root}/") })
-        "#{names} loaded before saboteur started coverage (a require ran before the " \
-          "executable's Coverage.start - commonly the gemspec requiring the library while bundler/setup " \
-          "evaluates it, or RUBYOPT -r), so no test can ever cover #{files.size > 1 ? 'them' : 'it'}. " \
-          "Let the test suite load these " \
-          "files; a gemspec should require only its version file."
+        "#{names} can never be covered: loaded before saboteur started coverage\n  " \
+          "a require ran before the executable's Coverage.start, commonly the gemspec requiring the " \
+          "library while bundler/setup evaluates it, or RUBYOPT -r\n  " \
+          "Let the test suite load these files; a gemspec should require only its version file."
       end
 
       # Bootsnap is named only when it is loaded: blaming a library the app