saboteur 0.11.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd9ced23a90f2f769ccf934e50949a8d9b04324fe86aeec72c8d0de896129ed
-  data.tar.gz: 3c9f5628615aefcaecac88474d2badb925e57d32d17066fc0afeef642eced780
+  metadata.gz: 74914fa96e0e644c7615013b6ad8a014c3c74b01e9b154931f2087fa0685dd31
+  data.tar.gz: 3265c82c7383a4ec2ce6355c009fc5816822e96334224e05a3cf6dac05404504
 SHA512:
-  metadata.gz: 44eb555775d94aa27ff1bf1f6b8a425faf973157bc8da3c9cbf66a337551699c63cbeba11dae6e5d9860f80002125dc60a08569d381a8f48034537b99c622a7b
-  data.tar.gz: bd5801edf6723c1442fed00d5c54cc82a278b23875f677427e9d3b3cc47d0c52a26bf0e7d0155a06e4de6c1eba71d25f3e724e1cfe22f180977efa09107e3256
+  metadata.gz: de0a4aa5db3d0403a46d9db2390fca263b9d7b433a9bbdb5d28049402c07d38ac75f2f68221bc4576ca3bc1a27c90c42aa7c62ba9f19d67eb6183507cfeef43b
+  data.tar.gz: 9d0286667bae0a37141efacd0547cb62d7185567ca8728f39be84902905f149f7d08f8eff2df07b2601083a8118a539d9d34fed06cfd47ec3840490c8ceb65a6

data/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes are documented here. The format follows
 [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
+## [0.11.1] - 2026-10-22
+
+### Added
+
+- Diff runs echo the real `--since` ref in hints and name the diff
+  scope in the reports (#1235, #1218, #1219), and `survivors` reads the
+  last report by default and refuses ambiguous digest prefixes (#1235,
+  #1189, #1188, #1192).
+- `baseline propose` tolerates untested subjects: proposability is the
+  gate at propose time, while strict evidence completeness stays where
+  it is required (#1168, #1141). The baseline command names what it is
+  doing, the file it writes and the follow-up command at every step,
+  and blockers resolve to subject, operator and reason plus a
+  remediation line (#1217, #1195, #1196).
+- The GitHub Action gains an opt-in `max-duration` input passed to
+  `--max-duration`, summary lines for exits 2/3/4/5/70, an annotation
+  on exit 4, and failure messages that each name the command or
+  setting that fixes them (#1220).
+- Incremental runs report reuse feedback (#1221), and the HTML report
+  gains a copy button on survivor blocks, print rules and aria fixes
+  (#1231).
+
+### Changed
+
+- Warning notices, the baseline tail and the CLI rescue paths render
+  through the colour palette (monochrome output is byte-identical), and
+  first runs are quieter: the Ruby 3.4 fiddle stdlib notice is dropped
+  during the guarded require, Rails mode no longer warns about the
+  harmless AR Pool Reaper thread, and the no-spec stop ends with a
+  clearer custom-map pointer (#1236, #1226, #1229, #1230).
+- Survivors rank by per-statement density first (the statement with
+  the most surviving mutants leads), then by thin coverage; ranking is
+  review priority only, with no score or exit-code effect (#1163).
+- `survivors --show` prints the complete detail - diff, replay command
+  with the run's seed, and a paste-correct ignore template (#1194,
+  #1217) - and unknown-command and doctor include errors are clearer
+  (#1194).
+- First-run DX: the footer ignore template pastes into `.saboteur.rb`
+  unchanged, install prints the next step, and lifecycle warnings are
+  quieter (#1217, #1221). The survivor-confirmation skip notice names
+  the real reason (#1231, #1184, #1177).
+- The HTML report is printable and collapsible, with clearer baseline
+  errors (#1179).
+
+### Fixed
+
+- Survivor confirmation no longer crashes the run (exit 70): a
+  confirmation failure degrades to a warning (#1164, #1140).
+- README hero output shows the right subject count (#1162), and the
+  exit-code docs match the gates (#1231, #1222).
+
 
 ## [0.11.0] - 2026-10-21
 

data/README.md

@@ -17,7 +17,7 @@
 
 ```text
 $ bundle exec saboteur pr
-saboteur 0.11.0: 1 subjects, 10 mutants, wall 0.70 s, seed 1 (repeat with --seed 1)
+saboteur 0.11.0: 2 subjects, 10 mutants, wall 0.70 s, seed 1 (repeat with --seed 1)
 Score: 80.0% (8/10 killed, tested subjects)
 saboteur: 8 killed, 2 survived in 1s - score 80.0%
 ```

data/lib/saboteur/baseline/command.rb

@@ -20,6 +20,7 @@ module Saboteur
           opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |value| set(:config, value) }
           opts.on("--subject EXPR", "Whole subject filter; repeatable") { |value| add_subject(value) }
           opts.on("--seed N", Integer, "Repeatable run seed") { |value| set(:seed, value) }
+          opts.on("--format FORMAT", "propose: terminal (default) or json") { |value| @format = value }
         end
       end
 
@@ -34,7 +35,7 @@ module Saboteur
           workflow = Baseline::Workflow.new(config: config, err: @err)
           baseline_action(workflow, action)
         end
-        @out.puts(JSON.generate(payload))
+        action == "propose" && @format != "json" ? print_proposal(payload) : @out.puts(JSON.generate(payload))
         payload.fetch("exit_code", CLI::EXIT_OK)
       rescue ConfigError, SystemCallError => e
         @err.puts("saboteur: #{e.message}")
@@ -44,13 +45,17 @@ module Saboteur
         CLI::EXIT_TOOL
       end
 
+      def baseline_path_required(action)
+        "--baseline PATH is required (for example: saboteur baseline #{action} --baseline baseline.json)"
+      end
+
       def parse_baseline(action)
         raise CLI::UsageError, "baseline expects check, propose or accept" unless %w[check propose
                                                                                      accept].include?(action)
 
         baseline_parser.parse!(@argv)
         raise CLI::UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
-        raise CLI::UsageError, "--baseline PATH is required" unless @baseline_path
+        raise CLI::UsageError, baseline_path_required(action) unless @baseline_path
         raise CLI::UsageError, "--proposal PATH is required" if action != "check" && !@proposal_path
         if action == "check" && (@proposal_path || @previous)
           raise CLI::UsageError,
@@ -58,6 +63,15 @@ module Saboteur
         end
         validate_epsilon(action)
         raise CLI::UsageError, "--previous needs a SHA-256" if @previous && !@previous.match?(/\A[0-9a-f]{64}\z/)
+
+        validate_format(action)
+      end
+
+      def validate_format(action)
+        unless @format.nil? || %w[terminal json].include?(@format)
+          raise CLI::UsageError, "--format must be terminal or json"
+        end
+        raise CLI::UsageError, "--format applies to propose only" if @format && action != "propose"
       end
 
       def validate_epsilon(action)
@@ -67,6 +81,36 @@ module Saboteur
         raise CLI::UsageError, "--epsilon must be between 0 and 100" unless (0.0..100.0).cover?(@epsilon)
       end
 
+      def print_proposal(payload)
+        @out.puts("baseline proposal written: #{payload.fetch('proposal')}")
+        survivors = payload.fetch("survivors")
+        @out.puts("  matched mutants: #{payload.fetch('candidates')} " \
+                  "(#{plural(survivors, 'survivor')} to reason about)")
+        gaps = payload.fetch("gaps", [])
+        unless gaps.empty?
+          names = gaps.map { |gap| gap.sub(/\A(subject_skipped|omitted):/, "") }
+          @out.puts("  proposed with #{plural(names.size, 'untested subject')}: #{names.join(', ')} - " \
+                    "the baseline cannot speak for them")
+        end
+        @out.puts("  next step: give each accepted survivor a reason in the proposal, then run: " \
+                  "saboteur baseline accept#{scope_flags} " \
+                  "--baseline #{payload.fetch('destination')} --proposal #{payload.fetch('proposal')}")
+      end
+
+      def plural(count, noun)
+        count == 1 ? "#{count} #{noun}" : "#{count} #{noun}s"
+      end
+
+      # accept re-verifies the recorded run settings, so the printed command
+      # repeats the scope flags this propose ran with.
+      def scope_flags
+        flags = +""
+        Array(options[:subjects]).each { |expr| flags << " --subject #{expr}" }
+        flags << " --seed #{options[:seed]}" if options[:seed]
+        flags << " --config #{options[:config]}" if options[:config]
+        flags
+      end
+
       def baseline_action(workflow, action)
         case action
         when "check" then workflow.check(path: @baseline_path, epsilon: @epsilon)

data/lib/saboteur/baseline/comparison.rb

@@ -62,7 +62,12 @@ module Saboteur
       end
 
       def outcome(current)
-        return "incomplete" unless current.fetch("complete") && issues.empty? && !current.fetch("candidates").empty?
+        # The proposability tier is the comparability gate: a run over soft
+        # gaps still speaks for the subjects it executed. Legacy documents
+        # without the split fall back to the strict flag and full issue list.
+        proposable = current.fetch("proposable") { current.fetch("complete") }
+        blockers = current.fetch("blockers") { current.fetch("issues") }
+        return "incomplete" unless proposable && blockers.empty? && !current.fetch("candidates").empty?
         return "incomplete" unless categories.fetch("errors").empty?
         return "review_required" if %w[new changed unmatched].any? { |name| !categories.fetch(name).empty? }
         return "review_required" if score&.fetch("exceeded")

data/lib/saboteur/baseline/completeness.rb

@@ -6,8 +6,15 @@ module Saboteur
     # Exact planned/result reconciliation, independent of survivor acceptance.
     class Completeness
       EXECUTED = %w[killed survived timeout].freeze
+      # Soft gaps limit what the baseline can speak for; they never refuse a
+      # proposal. Everything else is a hard blocker.
+      SOFT_PREFIXES = %w[subject_skipped: omitted:].freeze
       attr_reader :issues
 
+      def self.soft_gap?(issue)
+        SOFT_PREFIXES.any? { |prefix| issue.start_with?(prefix) }
+      end
+
       def initialize(planned:, results:, subjects:, stable_suite:, stable_inputs:, skipped_subjects:, omitted:,
                      generation_issues:)
         @issues = []
@@ -25,6 +32,20 @@ module Saboteur
         issues.empty?
       end
 
+      def blockers
+        issues.reject { |issue| self.class.soft_gap?(issue) }
+      end
+
+      def gaps
+        issues.select { |issue| self.class.soft_gap?(issue) }
+      end
+
+      # A proposal may be written over soft gaps (they are listed in it);
+      # only hard blockers refuse.
+      def proposable?
+        blockers.empty?
+      end
+
       private
 
       def validate_inventory(planned, subjects)

data/lib/saboteur/baseline/evidence.rb

@@ -10,8 +10,8 @@ module Saboteur
     # Validates the producer document before it can enter the acceptance path.
     # A claimed complete flag alone is never evidence of complete execution.
     class Evidence
-      FIELDS = %w[compatibility snapshot subjects candidates planned complete issues generation_events
-                  omissions discovery_failures inline_suppressions].freeze
+      FIELDS = %w[compatibility snapshot subjects candidates planned complete proposable issues blockers gaps
+                  generation_events omissions discovery_failures inline_suppressions].freeze
       COMPATIBILITY = %w[generator runtime config scope].freeze
       PLAN_FIELDS = %w[id identity context].freeze
 
@@ -27,6 +27,13 @@ module Saboteur
         validate_compatibility
         validate_generation
         validate_plan
+        blockers = @document.fetch("blockers")
+        gaps = @document.fetch("gaps")
+        unless @document.fetch("proposable") == blockers.empty? &&
+               (blockers + gaps).sort == @document.fetch("issues")
+          raise ConfigError, "baseline evidence: completeness tiers disagree"
+        end
+
         # Manifest owns exact candidate, identity, subject and acceptance shapes.
         Manifest.new(manifest(reasons: "validation"))
       rescue ArgumentError, KeyError, TypeError, NoMethodError => e
@@ -34,7 +41,8 @@ module Saboteur
       end
 
       def manifest(reasons: "")
-        metadata = document.fetch("compatibility").merge(document.slice("snapshot", "subjects", "complete", "issues"))
+        metadata = document.fetch("compatibility").merge(document.slice("snapshot", "subjects", "complete",
+                                                                        "proposable", "issues"))
         accepted = document.fetch("candidates").select { |entry| entry.fetch("status") == "survived" }.map do |entry|
           entry.slice("id", "context").merge("reason" => reasons)
         end

data/lib/saboteur/baseline/loader.rb

@@ -24,17 +24,30 @@ module Saboteur
         bytes = File.read(path)
         digest = Digest::SHA256.hexdigest(bytes)
         manifest = Manifest.new(JSON.parse(Text.utf8_strict(bytes)))
+        Evidence.new(restored_evidence(manifest))
+        [manifest, digest]
+      rescue Errno::ENOENT
+        raise ConfigError, "baseline file #{path} does not exist; " \
+                           "create it with saboteur baseline propose --baseline #{path}"
+      rescue SystemCallError, JSON::ParserError, ArgumentError => e
+        raise ConfigError, "baseline file: #{e.message}"
+      end
+
+      # The evidence snapshot a manifest stands for: its metadata, candidates
+      # and plan, with no generation events (nothing was generated).
+      def restored_evidence(manifest)
         metadata = manifest.to_h.fetch("metadata")
         candidates = manifest.candidates.values
-        restored = metadata.slice("snapshot", "subjects", "complete", "issues").merge(
+        issues = metadata.fetch("issues")
+        metadata.slice("snapshot", "subjects", "complete", "issues").merge(
+          "proposable" => metadata.fetch("proposable", metadata["complete"]),
+          "blockers" => issues.reject { |issue| Completeness.soft_gap?(issue) },
+          "gaps" => issues.select { |issue| Completeness.soft_gap?(issue) }
+        ).merge(
           "compatibility" => manifest.compatibility, "candidates" => candidates,
           "planned" => candidates.map { |entry| entry.slice(*Evidence::PLAN_FIELDS) },
           "generation_events" => [], "omissions" => [], "discovery_failures" => [], "inline_suppressions" => []
         )
-        Evidence.new(restored)
-        [manifest, digest]
-      rescue SystemCallError, JSON::ParserError, ArgumentError => e
-        raise ConfigError, "baseline file: #{e.message}"
       end
     end
   end

data/lib/saboteur/baseline/manifest.rb

@@ -4,12 +4,17 @@
 require "digest"
 require "json"
 
+require_relative "completeness"
+
 module Saboteur
   module Baseline
     # Validated, immutable human acceptance and the complete run it describes.
     class Manifest
       FORMAT = 1
-      METADATA = %w[generator runtime config scope snapshot subjects complete issues].freeze
+      METADATA = %w[generator runtime config scope snapshot subjects complete proposable issues].freeze
+      # Baselines written before the two-tier completeness split carry no
+      # proposable key; their strict complete flag is the proposability gate.
+      LEGACY_METADATA = (METADATA - %w[proposable]).freeze
       STATUSES = %w[killed survived timeout].freeze
 
       attr_reader :candidates, :accepted
@@ -48,8 +53,12 @@ module Saboteur
 
       def validate_metadata
         metadata = @document["metadata"]
-        fields!(metadata, METADATA, "metadata")
-        fail!("incomplete evidence") unless metadata["complete"] == true && metadata["issues"] == []
+        fail!("metadata fields") unless metadata.is_a?(Hash)
+        keys = metadata.keys.sort
+        fail!("metadata fields") unless [METADATA.sort, LEGACY_METADATA.sort].include?(keys)
+        proposable = metadata.fetch("proposable", metadata["complete"])
+        hard = metadata.fetch("issues").reject { |issue| Completeness.soft_gap?(issue) }
+        fail!("incomplete evidence") unless proposable == true && hard.empty?
         %w[generator runtime config scope snapshot].each do |name|
           fail!("metadata #{name}") unless metadata[name].is_a?(Hash) && !metadata[name].empty?
         end
@@ -121,7 +130,7 @@ module Saboteur
         current = candidates[entry["id"]]
         fail!("acceptance candidate") unless current && current["status"] == "survived"
         fail!("acceptance context") unless current["context"] == entry["context"]
-        text!(entry["reason"], "reason")
+        text!(entry["reason"], "reason on acceptance #{entry['id'][0, 16]} (write a non-blank reason)")
       end
 
       def fields!(value, fields, name)

data/lib/saboteur/baseline/run_evidence.rb

@@ -46,7 +46,9 @@ module Saboteur
         completeness = assess(observed, stable_suite, skipped_subjects, omissions, errors)
         document = { "compatibility" => compatibility, "snapshot" => @snapshot.to_h, "subjects" => @subjects,
                      "candidates" => observed, "planned" => @planned,
-                     "complete" => completeness.complete?, "issues" => completeness.issues,
+                     "complete" => completeness.complete?, "proposable" => completeness.proposable?,
+                     "issues" => completeness.issues, "blockers" => completeness.blockers,
+                     "gaps" => completeness.gaps,
                      "generation_events" => generation, "omissions" => omissions.map(&:to_h),
                      "discovery_failures" => discovery, "inline_suppressions" => suppressions }
         Engine::RunFingerprint.canonical_value(document)

data/lib/saboteur/baseline/workflow.rb

@@ -3,6 +3,7 @@
 
 require_relative "acceptance"
 require_relative "comparison"
+require_relative "identity"
 require_relative "loader"
 require_relative "../engine"
 require_relative "../text"
@@ -41,21 +42,48 @@ module Saboteur
         payload
       end
 
+      # Blockers carry only a digest and a status. Name the subject, operator
+      # and the engine's recorded reason, and say how to unblock the proposal.
+      def refuse_proposal(evidence, report)
+        blockers = evidence.fetch("blockers")
+        by_id = report.results.to_h do |result|
+          [Identity.new(subject: result.subject, mutation: result.mutation, root: @root).entry.fetch("id"), result]
+        end
+        blockers.each { |issue| @err.puts("saboteur: baseline proposal blocker: #{describe_blocker(issue, by_id)}") }
+        if blockers.any? { |issue| issue.start_with?("unexecuted:") }
+          @err.puts("saboteur: cover the skipped code with specs or narrow include, then propose again")
+        end
+        raise Error, "baseline proposal needs a proposable run"
+      end
+
+      def describe_blocker(issue, by_id)
+        match = /\Aunexecuted:([0-9a-f]{64}):(\w+)\z/.match(issue)
+        result = match && by_id[match[1]]
+        return issue unless result
+
+        detail = "#{result.subject.id} #{result.mutation.operator}"
+        detail += " - #{result.reason}" if result.reason
+        "#{issue} (#{detail})"
+      end
+
       def propose(proposal:, destination:, previous: nil)
         guard_artifacts(proposal, destination)
+        preflight_outputs(proposal, destination, previous)
         report = Engine.new(@config, err: @err, capture_evidence: true).call
-        unless report.run_evidence["complete"] == true
-          raise Error,
-                "baseline proposal requires complete execution evidence"
-        end
+        evidence = report.run_evidence
+        refuse_proposal(evidence, report) unless evidence["proposable"] == true
 
-        captured = Evidence.new(report.run_evidence)
+        captured = Evidence.new(evidence)
         store(captured.document.fetch("snapshot")).propose(document: captured.manifest,
                                                            evidence: captured.document, proposal: proposal,
                                                            destination: destination, previous: previous)
-        { "state" => "proposal", "proposal" => File.expand_path(proposal),
-          "destination" => File.expand_path(destination),
-          "survivors" => captured.manifest.fetch("accepted").size }
+        payload = { "state" => "proposal", "proposal" => File.expand_path(proposal),
+                    "destination" => File.expand_path(destination),
+                    "survivors" => captured.manifest.fetch("accepted").size,
+                    "candidates" => captured.manifest.fetch("candidates").size }
+        gaps = evidence.fetch("gaps")
+        payload["gaps"] = gaps unless gaps.empty?
+        payload
       end
 
       def accept(proposal:, destination:, previous: nil)
@@ -80,12 +108,20 @@ module Saboteur
           extras = saved.inventory.select { |entry| entry.kind == "extra" }.map do |entry|
             { path: input_path(entry.path), required: entry.required }
           end
-          Engine::RunFingerprint.new(config: @config, extra_files: extras).verify(saved).unchanged
+          raise_unless_unchanged(Engine::RunFingerprint.new(config: @config, extra_files: extras).verify(saved))
         end
         Acceptance.new(directory: File.join(Identity.canonical_path(@config.path("cache_dir")), "baseline-evidence"),
                        protected_paths: protected, verify: verifier, require_evidence: true)
       end
 
+      def raise_unless_unchanged(result)
+        return true if result.unchanged
+
+        detail = result.changes.map { |change| "#{change.path} #{change.reason}" }.join(", ")
+        detail = "verification incomplete" if detail.empty?
+        raise ConfigError, "baseline inputs changed or unverified: #{detail}"
+      end
+
       def input_paths(snapshot)
         snapshot.inventory.map { |entry| input_path(entry.path) }
       end
@@ -94,6 +130,18 @@ module Saboteur
         path.start_with?("external:") ? path.delete_prefix("external:") : File.join(@root, path)
       end
 
+      # Cheap pre-checks before the full run; Acceptance re-verifies exclusively after it.
+      def preflight_outputs(proposal, destination, previous)
+        raise ConfigError, "baseline output exists: #{Identity.canonical_path(proposal)}" if File.exist?(proposal)
+
+        # Mirrors Acceptance#verify_previous so a doomed proposal fails before the run.
+        if previous.nil?
+          raise ConfigError, "baseline destination exists" if File.exist?(destination)
+        elsif !File.file?(destination) || Digest::SHA256.file(destination).hexdigest != previous
+          raise ConfigError, "baseline previous destination changed"
+        end
+      end
+
       def guard_artifacts(*paths)
         paths.each do |path|
           expanded = Identity.canonical_path(path)

data/lib/saboteur/baseline_health.rb

@@ -35,7 +35,10 @@ module Saboteur
 
     def call
       expected = @integration.all_tests.map(&:id)
-      raise Error, "baseline has no tests; check rspec_args and spec paths" if expected.empty?
+      if expected.empty?
+        raise Error, "baseline has no tests; check rspec_args and the suite filters, " \
+                     "then run saboteur doctor --suite again"
+      end
 
       first = check_run(1, expected)
       second = check_run(2, expected)

data/lib/saboteur/cli/dirty_tree_notice.rb

@@ -1,6 +1,9 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../reporter/palette"
+require_relative "../reporter/notice"
+
 module Saboteur
   class CLI
     # The uncommitted-work warning printed before a run (#334). Extracted
@@ -21,7 +24,10 @@ module Saboteur
                   else
                     config
                   end
-        DirtyTreeWarning.for(warning, config_path: options[:config])&.then { |text| @err.puts(text) }
+        DirtyTreeWarning.for(warning, config_path: options[:config])&.then do |text|
+          palette = Reporter::Palette.for(@err, mode: @color || :auto, overrides: warning["palette"])
+          @err.puts(Reporter::Notice.paint(palette, text))
+        end
       end
     end
   end

data/lib/saboteur/cli/doctor_command.rb

@@ -22,13 +22,22 @@ module Saboteur
 
       def doctor_command = help_requested? ? show_help("doctor") : doctor
 
+      # The environment is healthy only if a run would have something to
+      # mutate: the same empty source set `run` refuses (exit 2).
+      def doctor_verdict
+        return EXIT_OK unless config.included_files.empty?
+
+        @err.puts("saboteur: #{empty_source_set_message}")
+        EXIT_USAGE
+      end
+
       def doctor
         doctor_parser.parse!(@argv)
         raise UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
 
         options[:tests]&.each { |test| require_existing_test(test) }
         Doctor.new(config, out: @out, suite: options[:suite] || options.key?(:tests)).call
-        EXIT_OK
+        doctor_verdict
       rescue ConfigError => e
         @err.puts("saboteur: #{Text.display_safe_lines(e.message)}")
         EXIT_USAGE

data/lib/saboteur/cli/exit_status.rb

@@ -60,9 +60,10 @@ module Saboteur
       # must not exit 0 with score n/a and green-light an untested change.
       def unverifiable_scope?(report)
         if unverifiable_review?(report)
-          report.skipped_subjects.each do |subject, reason|
-            @err.puts(subject.skipped_gate_sentence(reason, report.root))
-          end
+          # A text run already printed each skip up front; json and agent
+          # runs read this sentence as the exit explanation (#1227).
+          skips = %w[json agent].include?(@format) ? report.skipped_subjects : report.unannounced_skips
+          skips.each { |subject, reason| @err.puts(subject.skipped_gate_sentence(reason, report.root)) }
           return true
         end
         return false unless unverifiable_unreachable?(report)

data/lib/saboteur/cli/explicit_sources.rb

@@ -39,7 +39,7 @@ module Saboteur
       # A test may carry an example selector: spec/a_spec.rb:12 or spec/a_spec.rb[1:2].
       def require_existing_test(test)
         path = test.sub(/(:\d+|\[[\d:,]+\])+\z/, "")
-        raise UsageError, "test file not found: #{test}" unless File.exist?(path)
+        raise UsageError, "test file not found: #{test}; check the path or drop --test" unless File.exist?(path)
       end
     end
   end

data/lib/saboteur/cli/failure_output.rb

@@ -25,7 +25,7 @@ module Saboteur
       end
 
       def usage_error(message = nil)
-        @err.puts(message) if message
+        @err.puts(Reporter::Palette.for(@err, mode: @color || :auto).paint(:fail, message)) if message
         @err.puts(USAGE)
         agent_failure(message || USAGE, EXIT_USAGE)
       end
@@ -43,7 +43,7 @@ module Saboteur
       # name must not become a workflow command in the CI log).
       def report_failure(error, exit_code)
         message = Text.display_safe_lines(error.message)
-        @err.puts("saboteur: #{message}")
+        @err.puts(Reporter::Palette.for(@err, mode: @color || :auto).paint(:fail, "saboteur: #{message}"))
         @err.puts(verdict_line(EXIT_BASELINE_RED)) if exit_code == EXIT_BASELINE_RED
         agent_failure(message, exit_code)
       end

data/lib/saboteur/cli/presets.rb

@@ -14,6 +14,11 @@ module Saboteur
                       --html .saboteur/audit-report.html]
       }.freeze
 
+      # What a new user types first; there is no such command, the Rails
+      # generator writes the starter files.
+      SETUP_WORDS = %w[init install setup].freeze
+      SETUP_HINT = "To set up a Rails app, run: bin/rails generate saboteur:install"
+
       # Preset flags that take a separate value token: the pairs a user
       # flag can override in the banner (#666).
       VALUE_FLAGS = %w[--baseline-passes --max-duration --since --operators --json --html].freeze
@@ -21,7 +26,12 @@ module Saboteur
       private
 
       def preset_or_usage_error(command)
-        PRESETS.key?(command) ? preset(command) : usage_error
+        return preset(command) if PRESETS.key?(command)
+
+        # A typo'd command is not a run: say so before the usage line.
+        @err.puts("unknown command: #{command}. Run 'saboteur help' for the commands.") if command
+        @err.puts(SETUP_HINT) if SETUP_WORDS.include?(command)
+        usage_error
       end
 
       def preset(name)

data/lib/saboteur/cli/run_command.rb

@@ -30,7 +30,10 @@ module Saboteur
         validate_run_options
         warn_dirty_tree
 
-        config.deprecation_warnings.each { |warning| @err.puts("saboteur: #{warning}") }
+        notices = Reporter::Palette.for(@err, mode: @color || :auto, overrides: config["palette"])
+        config.deprecation_warnings.each do |warning|
+          @err.puts(Reporter::Notice.paint(notices, "saboteur: #{warning}"))
+        end
 
         return preview if options[:list_operators] || options[:dry_run]