saboteur 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e6b6d8e50fff66a62fceb86427129fb8223251089a56a538265cc2ca0437559
-  data.tar.gz: 5ccca5b91560563ef6b6c2da93dc9191498074b714793e8586cbfa57dfbecf66
+  metadata.gz: 30c6af46486b9fc1138b568c45934cc895f786a79ea5215607f493a5a7d5af68
+  data.tar.gz: a7a8038afc6166347fac807028cf7f45acecbb7e4c27e32f8917c4167b805bac
 SHA512:
-  metadata.gz: 1adf971a3548189acb63ee19e382d98f91cc9c3b9980bdc9d92e903754ab96d1aebb706c95cc8b7da4ee3a4eb851311b94b35f3f599213aa7e1e787adceff282
-  data.tar.gz: b11f8aba3ffa20e5f97d68ef2422eca609c6277e0d8dc408d30a70851342d1f64c97a563224a26a6f0d1652321e200242230bc85e5e62cd02428b7a8e21e24b5
+  metadata.gz: 66817191adf235c1fb6adb41d3218704557d2d3305fab299f17cc38bb3b392733f0a52615d84aadb5e4fd940046db9336de9efa178b205d58cc8e1c61374c25a
+  data.tar.gz: 132649f6b81d5ee312341a032df36b890af481704deee6c4b5cd4a013736c857ddc7887b27318409a1db05ea2621cbc8b2791ff4d0c40d3509810a6e13f7a405

data/CHANGELOG.md

@@ -6,6 +6,221 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-20
+
+### Added
+
+- Five new mutation operators: `and_assign` drops the guard on `&&=`
+  (#873), `jump_value` replaces unchecked early-exit values (#875),
+  `rescue_removal` removes exception handlers no test reaches (#877),
+  `when_removal` removes case branches no test takes (#887), and
+  `unary_removal` removes signs and complements no test sees (#890).
+- `--resume DIR` keeps verdicts in a directory across runs, with a
+  manifest check on the directory (#840, #831), and `--incremental`
+  checkpoints verdicts while the run is going (#820, documented in #822).
+- Partial and parallel coverage: `c.coverage_parts` deals the suite into
+  parts built in parallel (#741: #769, #772, #774, #776), keeps each
+  finished part when a build stops (#860), and reuses the saved parts
+  when a parallel build is rerun (#862). The partial map merge and an
+  opt-in shadow run compare a partial rebuild against the full map
+  (#829, #832), and `partial_coverage = "use"` skips the full build when
+  only spec files or covered sources changed, rerunning just the stale
+  spec files and merging them into the earlier map (#918).
+- TracePoint coverage recorders: `MethodCalls` records Ruby method
+  entries (#794, #795), a line-hits recorder reads branches once per
+  spec file (#894, #897), and `c.coverage_recorder = "trace"` picks the
+  TracePoint build (#898).
+- Constant-reference spec selection: a spec that requires a spec-less
+  file counts as its reference reader (#876, #879), a stop that keeps a
+  hub file's cap says how many specs reference it (#881), and the agent
+  JSON provenance reports and flags findings whose specs were chosen by
+  reference (#884, #885).
+- The GitHub Action posts surviving mutants as pull-request review
+  comments on the lines the PR head has (#788, #789, #793), matches the
+  review comment bot login without regard to case (#791), documents the
+  review comment inputs (#790), and exposes max-timeouts and max-errors
+  as inputs (#246, #767).
+- Integration targets: a target can name its own gemfile (#900), carry
+  patch, env and recorder options (#899), and run setup commands and add
+  gems (#910). doorkeeper, paper_trail, cancancan and lobsters join the
+  recorder-parity targets (#901, #908, #912).
+- The JSON report adds per-gate score breakdowns (#473, #766) and a
+  `saboteur.complete` field (#784).
+- A real-bug corpus runner with a manual CI workflow, and the s-z and
+  i-r corpus slices (#652: #915, #916).
+- A coverage cache miss says why it missed and what changed (#812), and
+  spec shards balance by recorded per-example run time (#747, #748).
+- Warnings across the survivor, sandbox grant, shadow, worker, budget
+  and `--since`/`--subject` messages lead with the outcome and name the
+  remedy, per the documented message style (#332 series, #796).
+
+### Fixed
+
+- `--since` ignores a line whose only change is its trailing comment
+  (#892, fixed in #921).
+- `script/rspec-shard` no longer dies of SIGPIPE on a long spec list
+  (#878).
+- `or_assign` no longer mutates constant targets inside a def (#874).
+- A test that suspends Coverage no longer breaks the map build; Coverage
+  resumes after it (#869).
+- Worker pool cleanup no longer leaks live entries or masks errors, and
+  keeps unregistering workers when the orphan sweep goes blind (#762:
+  #770, #771); containment and the live registry survive a blind process
+  table (#762: #764).
+- A timed-out Gemfile resolver no longer blocks on escaped-grandchild
+  pipes, and the resolver-pipe specs reap escaped grandchildren (#734,
+  #750). A `path:` source equal to the project root rebases onto the
+  copy root (#729), external test-command `path:` sources are refused or
+  rebased (#644, #721), and the BUNDLE_GEMFILE pin gaps close with
+  lockfile-mismatch refusals (#732).
+- A cached coverage map is read as untrusted input: its field types,
+  durations and loaded files are checked, non-finite values are
+  rejected, and the inputs snapshot binds to the map and the runtime
+  (#853, #854, #859, #825). Stored verdicts are type-checked before
+  reuse (#842).
+- Cache files and the coverage map write through an exclusive private
+  temp file (#846, #850).
+- Registry DSL blocks in Ohai/Puppet style promote their defs to
+  subjects (#700, #727).
+- The baseline checks the unchanged suite in the coverage build's parts
+  instead of a separate pass (#930).
+
+### Security
+
+- CI workflow-command injection is closed at every sink: the unmatched
+  whole_file pattern (#856), repo-controlled file names in the
+  constant-safety warnings (#857), name_list items (#858),
+  repo-controlled names in the syntax, custom map and sandbox grant
+  warnings (#870), every Diagnostics warning line (#871), the terminal
+  report at one choke point (#872), the stop and gate messages (#919),
+  and the CLI error sinks (#917, fixed in #920).
+- The review comment planner is hardened against untrusted input (#783),
+  and the Action fetches the pull request base with the token in a step
+  of its own, with the token-handling scripts pinned (#797, #798).
+
+### Documentation
+
+- The getting-started guide shows a gem-installed run (#815), the
+  config-key table documents every key and the Rails config points at it
+  (#809), the Action guide documents a per-path score gate (#817),
+  `--incremental` verdict saving is documented (#822), and the warning
+  and note style convention is written down (#796).
+
+## [0.8.1] - 2026-10-18
+
+### Added
+
+- Positional call-argument swap operator (#653): swaps adjacent positional
+  arguments at call sites, catching specs that do not pin argument order.
+- After the first timed baseline pass, saboteur projects the remaining
+  baseline+coverage cost against `--max-duration` and warns up front when
+  the budget barely fits or is exceeded, naming how much time mutants get
+  and the remedies (#637). A `--max-duration` run that ends with exit 4
+  and 0 mutants now headlines "no mutants ran", and the flag's help states
+  what the clock covers: it starts at engine entry and includes the
+  baseline and coverage phases.
+- fiddle is no longer a hard dependency: it loads lazily through one door
+  that refuses with every working fix named when it is missing, and the
+  sandbox layers fail closed on refusal (#639).
+
+### Fixed
+
+- The DCO checks no longer disagree: CI's check-dco, preflight, and the
+  panel gate all require the Signed-off-by line to be a real git trailer
+  after a blank line (#646).
+- When a changed file matches no spec by id hint, saboteur names the exact
+  ids it looked for (`warn_unmatched_whole_file`, `--since` scoped) (#635).
+- `saboteur pr --since` on a spec-only or docs-only diff no longer warns
+  that "the whole suite runs" - it announces there is nothing to test,
+  matching the zero-subject run that follows (#607).
+- On macOS the degraded-sandbox message no longer claims the kernel "lacks
+  Landlock (needs Linux 6.2+)"; it says macOS has no Landlock and points
+  at `c.sandbox = "seatbelt"` (#667).
+- The preset banner shows the effective flags, including explicit
+  `--since` refs and flag=value spellings (#666).
+- Running saboteur without rspec-core in the bundle (for example a
+  Minitest project) fails as a usage error (exit 2) naming docs/minitest.md,
+  instead of an internal error pointing at the RSpec-only `c.integration`
+  remedy (#610). A baseline that fails with NoMethodError in a suite whose
+  spec_helper requires minitest now warns the suite looks like Minitest
+  running under RSpec, with the symptom and count (#626).
+- Test-file guessing looks for specs below a flattened namespace
+  (rubocop-ast style layouts) (#586), and when a layout strips directories
+  between source and spec trees it picks the unique spec by parent
+  directory and basename instead of failing or guessing wrong (#600).
+- A `--subject` pattern that names an attr_reader, attr_writer or
+  attr_accessor method no longer says "matches no subject"; the method
+  exists but has no body to mutate, and the message says so (#373).
+- Load errors in the target app's boot are reported with the tool's own
+  frames filtered out, with `--verbose` restoring the full backtrace (#608).
+- If a spec file loaded Ruby code before saboteur started coverage,
+  whole-suite runs no longer report "5 subjects, 0 mutants"; saboteur
+  names up to 5 preloaded files with cause and remedy and exits 3. With
+  `--test` it warns and continues (#686).
+- An empty or docs-only `--since` range exits 0 with a "nothing to test"
+  notice instead of failing (#659), and a run no longer floods stderr with
+  Ruby's "possibly useless use of nil in void context" compile warnings
+  when the host suite enables warnings (#656).
+- Running saboteur in a project with no RSpec suite stops with a single
+  line naming the problem and pointing to docs/minitest.md, instead of one
+  line per source file; specs outside spec/ fall back to the per-file stop
+  with `--test`/`--all`. Exit code unchanged (2) (#606).
+- Whole-file targets no longer error "already initialized constant" in
+  strict-warning suites when the app lazily requires the same file (#632).
+- Doctor's macOS degraded-sandbox output names the way out:
+  `c.sandbox = "seatbelt"` with the guide link, or `c.sandbox = false` (#667).
+- Load-time vetting no longer rejects `class << self` or `/re/.freeze`,
+  and the constant-skip warning cites a one-line excerpt plus line instead
+  of whole class bodies (#664). Vetting clears Struct/Data factories,
+  public_constant/private_constant, and lambda literals so those files
+  keep their mutation subjects (#537).
+- A spec load that quits because the suite auto-starts SimpleCov/SingleCov
+  names the suspect and both guard styles, instead of an opaque "No
+  examples found" (#645).
+- A sqlite :memory: database with a schema but zero rows hints at
+  require-time seed data lost across the fork, with the
+  before(:suite)/after_fork remedy and the `c.hooks` wiring (#594).
+- The early-stopped summary headline reads selected versus attempted, for
+  example "57 mutants selected, 4 attempted" (#582).
+- The dirty-tree warning headline says "uncommitted or untracked change(s)"
+  so a tree of only scratch files is not read as edits (#604).
+- Custom-map load errors name unsupported template syntax before glob
+  validation, literal map paths are preserved, and mixing numbered and
+  named map templates is rejected at load with a clear error (#642).
+- The sqlite in-memory database fork-loss hint includes the exact
+  `c.hooks` configuration needed to load the suggested after-fork hooks
+  file (#593).
+- A subject the `--max-duration` budget stops mid-list no longer drops the
+  kills it already measured: the truncated subject's completed kills are
+  confirmed uncapped (#588).
+- Shell-exported RUBYLIB entries that bundler's scrub drops are restored
+  (#584), `spec/` is on the load path for non-Rails boots too (#615), and
+  RSpec core loads before configured boot helpers so non-Rails helpers can
+  call RSpec.configure (#616).
+- `--test-command` warns when one ruby is handed several test files: ruby
+  executes only the first, so the rest never ran and their mutants
+  silently survived (#611).
+- Dry-run excludes statically unsupported subjects, such as methods
+  defined inside blocks, from planned mutant totals and reports the skip
+  reason (#651).
+- Non-String integration assignments fail with a file-and-line
+  configuration error before fingerprinting or boot (#614).
+- Baseline failures outside examples say so and show the log tail instead
+  of an empty failed-example list (#581).
+
+### Documentation
+
+- The flaky-tests and survivors guides catch up with 0.8.0 (#683), and
+  design.md explains the load-time vetting safelist for constant replay
+  under `--since`, including what it cannot account for (#537).
+- Docs drift: the pinned saboteur-vs-mutineer benchmark report names the
+  version it measured (0.1.0), and the compare page scopes its kill
+  re-check claim to fresh kills (#657).
+- The README quick start covers the inference-miss exit 2 and its
+  recovery, the install block leads with Bundler, the quick-start anchor
+  matches its heading, and a no-warranty disclaimer joins the license
+  section (#658, #657, #599).
+
 ## [0.8.0] - 2026-10-18
 
 ### Added

data/README.md

@@ -21,26 +21,44 @@ code, so a broken suite never counts as a kill.
 **Docs, benchmarks and guides live on the site:
 [vamsipavanmahesh.github.io/saboteur](https://vamsipavanmahesh.github.io/saboteur/)**
 
-<a id="60-second-quick-start"></a>
+<a id="30-second-quick-start"></a>
 ## 30-second quick start
 
 You need Ruby 3.3 or newer, RSpec, and Linux or macOS with `fork`.
 
-```sh
-# Install the gem:
-gem install saboteur
+Prerequisite: the sandbox layers use fiddle, which ships with Ruby
+(a default gem on Ruby 3.x). On Ruby 4.0+, where fiddle is a bundled
+gem, add `gem "fiddle"` to your Gemfile. If saboteur refuses a run
+because fiddle cannot load: reinstall Ruby, run `gem install fiddle`,
+or install libffi headers (libffi-dev on Debian/Ubuntu, libffi-devel
+on Fedora/RHEL) and reinstall fiddle. libffi headers are required only
+when Ruby's shipped fiddle is missing or must be installed standalone.
 
-# Or add it to the Gemfile:
+```sh
+# Add it to your project's Gemfile:
 bundle add saboteur --group test
 
-# Either way:
+# Then:
 bundle exec saboteur run
 ```
 
+Outside a Bundler project, `gem install saboteur` gives the same
+executable - run it there as plain `saboteur run`, without
+`bundle exec`.
+
 The first run builds a coverage map of which tests touch which code. The
 map is cached and reused while your code and tests stay unchanged, so
 later runs start fast.
 
+If the first run stops with exit 2 and `no spec found for ...`, saboteur
+could not map a source file to its spec: it matches by path first, then
+by parent directory and basename when the layout strips directories,
+and it refuses to guess wrong. Point it at the specs yourself - set
+`test_selection = :all` in `config/saboteur.rb` to run the whole suite
+against each mutant, pass `--test spec/...` to name the specs, or
+declare a custom map
+([monorepos and the custom map](docs/guides/monorepo-and-custom-map.md)).
+
 On a branch, `bundle exec saboteur pr` mutates only the methods you
 changed relative to `main`, with one baseline pass and a ten-minute
 budget. If the budget stops the run, it exits 4 and prints `partial: X
@@ -109,6 +127,16 @@ the macro itself `ran at load` instead of letting its mutants survive.
   before a kill is rejected, so its mutants are still scored.
 - **Reports for people and tools.** Terminal, HTML, a Stryker-compatible
   JSON report, and a stable agent JSON API with a deprecation policy.
+  The GitHub Action posts surviving mutants as review comments on the
+  diff lines of the pull request.
+- **Resumable runs.** `--resume DIR` keeps verdicts across runs and
+  `--incremental` checkpoints them while the run is going, so a stopped
+  run picks up where it left off.
+- **Faster coverage builds.** `c.coverage_parts` builds the coverage map
+  in parallel parts, `partial_coverage = "use"` rebuilds only the stale
+  spec files and merges them into the saved map, and
+  `c.coverage_recorder = "trace"` builds the map with a TracePoint
+  recorder.
 - **A plan before the run.** `saboteur run --dry-run --format json` prints
   the versioned [mutant inventory](docs/dry-run-json.md) - every planned
   mutant with its stable digest and edits - without booting the suite.
@@ -247,6 +275,16 @@ on the site and [docs/benchmark](docs/benchmark/) in this repo.
 - [Contributing](CONTRIBUTING.md) - every commit needs a DCO `Signed-off-by` line
 - [Design notes](docs/design.md)
 
+## Disclaimer
+
+saboteur is provided "as is", without warranty of any kind, express or
+implied. In no event shall the authors or copyright holders be liable
+for any claim, damages or other liability arising from its use -
+including damage caused by mutating your code or by running unusual
+DSLs and metaprogramming-heavy code. Mutation testing runs your test
+suite against deliberately broken code; run it on a clean, committed
+tree or a CI checkout. The full text is in [LICENSE](LICENSE).
+
 ## License
 
 [MIT](LICENSE).

data/exe/saboteur

@@ -11,7 +11,7 @@
 # (one line, invalid bytes scrubbed, bounded length) still exits 3.
 begin
   require "coverage"
-  Coverage.setup(lines: true, methods: true, branches: true) if Coverage.state == :idle
+  Coverage.setup(lines: true, branches: true) if Coverage.state == :idle
 
   require "saboteur/crash_report"
 rescue LoadError, StandardError => e
@@ -27,7 +27,11 @@ end
 # ones. The engine suspends counting right after boot and reads the
 # counters as the map's load lines (a forked child would not inherit them).
 begin
-  Coverage.resume if ARGV.first == "run" && Coverage.state == :suspended
+  if ARGV.first == "run" && Coverage.state == :suspended
+    require "saboteur/method_calls"
+    Saboteur::MethodCalls.boot
+    Coverage.resume
+  end
 
   require "saboteur/cli"
 

data/lib/saboteur/attribute_finder.rb

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "deep_source"
+require_relative "subject"
+
+module Saboteur
+  # Finds the methods attribute macros generate - attr_reader, attr_writer,
+  # attr_accessor - so a --subject pattern naming one can be answered with
+  # "defined by attr_reader, no body to mutate" instead of the
+  # pattern-format hint (#373). The generated method has no body saboteur
+  # can mutate, so it is never a mutation subject. Only a receiverless
+  # call with literal symbol or string names defines anything nameable;
+  # like SubjectFinder, a macro inside a block binds to an unknowable
+  # self and is skipped.
+  class AttributeFinder
+    # One generated method: id follows Subject#id ("Owner#name",
+    # "Owner.name", "Owner#name="), macro is the call that made it.
+    Found = Data.define(:id, :macro)
+
+    MACROS = %i[attr_reader attr_writer attr_accessor].freeze
+
+    def call(file)
+      result = Prism.parse(File.binread(file), filepath: file)
+      return [] if result.failure?
+
+      DeepSource.check!(result.value, file)
+
+      found = []
+      walk(result.value, [], found)
+      found
+    end
+
+    private
+
+    def walk(node, nesting, out, in_block: false)
+      return if node.nil?
+
+      case node
+      when Prism::BlockNode, Prism::LambdaNode
+        walk(node.body, nesting, out, in_block: true)
+      # A keyword class or module re-enters the lexical scope: a macro
+      # inside binds on the class even when the class sits in a block
+      # (mirrors ConstantSubjectFinder).
+      when Prism::ModuleNode
+        walk(node.body, nesting + [Scope.new(kind: :module, path: node.constant_path.slice)], out)
+      when Prism::ClassNode
+        walk(node.body, nesting + [Scope.new(kind: :class, path: node.constant_path.slice)], out)
+      when Prism::SingletonClassNode
+        walk_singleton_class(node, nesting, out)
+      when Prism::CallNode
+        record_macro(node, nesting, out, in_block: in_block)
+        node.compact_child_nodes.each { |child| walk(child, nesting, out, in_block: in_block) }
+      else
+        node.compact_child_nodes.each { |child| walk(child, nesting, out, in_block: in_block) }
+      end
+    end
+
+    # `class << self`: attribute macros inside define singleton methods on
+    # the enclosing class (mirrors SubjectFinder's singleton defs).
+    def walk_singleton_class(node, nesting, out)
+      return unless node.expression.is_a?(Prism::SelfNode)
+      return if nesting.empty? || nesting.last.sclass?
+
+      walk(node.body, nesting + [Scope.new(kind: :sclass, path: "self")], out)
+    end
+
+    def record_macro(node, nesting, out, in_block:)
+      return unless MACROS.include?(node.name) && node.receiver.nil? && node.block.nil?
+      return if in_block
+
+      owner = owner_path(nesting)
+      return unless owner
+
+      separator = nesting.last&.sclass? ? "." : "#"
+      node.arguments&.arguments.to_a.each do |argument|
+        name = macro_name(argument)
+        next unless name
+
+        generated_names(node.name, name).each do |method_name|
+          out << Found.new(id: "#{owner}#{separator}#{method_name}", macro: node.name)
+        end
+      end
+    end
+
+    # The methods one macro call generates per named attribute: a reader, a
+    # writer, or both for attr_accessor.
+    def generated_names(macro, name)
+      case macro
+      when :attr_reader then [name]
+      when :attr_writer then ["#{name}="]
+      else [name, "#{name}="]
+      end
+    end
+
+    def macro_name(argument)
+      argument.unescaped if argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)
+    end
+
+    # Lexical path of the enclosing class/module; `class ::Foo` restarts at
+    # the top. A `class << self` scope changes the separator, not the path.
+    def owner_path(nesting)
+      path = +""
+      nesting.each do |scope|
+        next if scope.sclass?
+
+        segment = scope.path
+        path.clear if segment.start_with?("::")
+        path << "::" unless path.empty?
+        path << segment.delete_prefix("::")
+      end
+      path.empty? ? nil : path
+    end
+  end
+end

data/lib/saboteur/baseline/run_evidence.rb

@@ -3,6 +3,7 @@
 
 require_relative "identity"
 require_relative "completeness"
+require_relative "../config"
 require_relative "../engine/run_fingerprint"
 
 module Saboteur
@@ -11,7 +12,7 @@ module Saboteur
     # This does not attest external database, network or environment state.
     class RunEvidence
       SAFE_DROPS = %w[unchanged duplicate].freeze
-      OUTPUT_SETTINGS = %w[cache_dir json_report html_report score_history].freeze
+      OUTPUT_SETTINGS = Config::OUTPUT_KEYS
 
       def initialize(config:, extra_files: [])
         @config = config

data/lib/saboteur/cli/agent_provenance.rb

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Agent-mode provenance: the record a JSON report carries so its rerun
+    # and replay commands reproduce the run exactly (#334). Extracted from
+    # CLI; the builder and its settings helpers are private to the mixin.
+    module AgentProvenance
+      private
+
+      def agent_provenance(report, tree, engine)
+        Reporter::Agent::Provenance.new(
+          ref: config["since"], seed: report.seed, head: tree.head, working_tree: tree.label,
+          changed_files: tree.changed_files, mode: agent_mode, json_report: config.path("json_report"),
+          subjects: Array(config["subjects"]), tests: Array(engine.guessed_tests || config["tests"]),
+          sources: @sources || [],
+          config_path: options[:config], digest: options[:id], cache: config["cache"],
+          incremental: config["incremental"], settings: agent_settings, typed_settings: typed_settings,
+          referenced: report.referenced
+        )
+      end
+
+      # The settings keys typed on the command line: a typed empty operator
+      # list may clear a config value, so the generated commands keep it.
+      def typed_settings = options.keys & Reporter::Agent::Commands::SETTING_FLAGS.keys
+
+      # A whole-suite run records its scope as --all, so the generated rerun
+      # and replay commands do not default back to inference (which can exit
+      # 2 in a project with a spec-less source file).
+      def agent_settings
+        settings = options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
+                          .merge(operators: config["operators"], exclude_operators: config["exclude_operators"])
+        # The effective mode: named tests win over a configured whole-suite
+        # selection by precedence, so all is recorded only when no tests
+        # resolved - otherwise the follow-up commands would carry both --all
+        # and --test, which the CLI rejects.
+        settings[:all] = true if (config["all"] || config["test_selection"] == "all") && config["tests"].empty?
+        # CLI-only switches that change candidate availability or boot, so a
+        # printed rerun/replay must keep them (config-file settings like
+        # arid/hazard patterns, whole-file, require, rspec_args and rails ride
+        # along through --config or the default config path).
+        settings[:allow_hazardous] = true if options[:allow_hazardous]
+        settings[:allow_focus] = true if options[:allow_focus]
+        # An explicit false (--no-max-duration-ok over a config true) is a
+        # setting too: dropping it would silently re-enable the config value.
+        settings[:max_duration_ok] = options[:max_duration_ok] unless options[:max_duration_ok].nil?
+        settings
+      end
+
+      def agent_mode
+        return "replay" if options[:id]
+        return "diff" if config["since"]
+
+        @sources&.any? ? "files" : "full"
+      end
+    end
+  end
+end

data/lib/saboteur/cli/dirty_tree_notice.rb

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The uncommitted-work warning printed before a run (#334). Extracted
+    # from CLI.
+    module DirtyTreeNotice
+      private
+
+      # Mutants run your code, and a mutant of code that writes or deletes files
+      # can change the tree. Say so up front when uncommitted work is at stake.
+      # The scope the warning names is the configured one: positional source
+      # operands narrow the run after the warning, so the include/exclude they
+      # imply stay out of its config (#309, #503 review).
+      def warn_dirty_tree
+        warning = if @sources
+                    Config.load(path: options[:config],
+                                overrides: overrides.except(:include,
+                                                            :exclude))
+                  else
+                    config
+                  end
+        DirtyTreeWarning.for(warning, config_path: options[:config])&.then { |text| @err.puts(text) }
+      end
+    end
+  end
+end

data/lib/saboteur/cli/doctor_command.rb

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # `saboteur doctor`: environment report and optional unchanged suite
+    # passes, never mutations (#334). Extracted from CLI by command.
+    module DoctorCommand
+      def doctor_parser
+        OptionParser.new do |opts|
+          opts.banner = "Usage: saboteur doctor [--config PATH] [--seed N] [--suite] [--test PATH]"
+          opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |value| set(:config, value) }
+          opts.on("--seed N", Integer, "Seed for the two baseline runs (default 1)") { |value| set(:seed, value) }
+          opts.on("--suite", "Also run the unchanged suite twice (slow on a large suite)") { set(:suite, true) }
+          opts.on("--test PATH", "Spec file or directory for the suite runs; repeatable. Implies --suite") do |value|
+            (options[:tests] ||= []) << value
+          end
+        end
+      end
+
+      private
+
+      def doctor_command = help_requested? ? show_help("doctor") : doctor
+
+      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
+      rescue ConfigError => e
+        @err.puts("saboteur: #{Text.display_safe_lines(e.message)}")
+        EXIT_USAGE
+      rescue Error => e
+        @err.puts("saboteur: #{Text.display_safe_lines(e.message)}")
+        EXIT_TOOL
+      end
+    end
+  end
+end

data/lib/saboteur/cli/error_cause.rb

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The detail line a "mostly errored" or "incomplete" exit message adds:
+    # the most common first line of the errored results' reasons, so a run
+    # that exits on its error count still names why (a worker killed by a
+    # signal, say) instead of leaving the cause in the stdout error list.
+    module ErrorCause
+      def self.incomplete(problem)
+        "saboteur: #{problem.size} mutant(s) errored or hit a resource limit, so the score is " \
+          "incomplete#{line(problem)}"
+      end
+
+      LIMIT = 200
+
+      # "" when no result carries a reason.
+      def self.line(errored)
+        reasons = errored.filter_map { |result| first_line(result.reason) }.reject(&:empty?)
+        return "" if reasons.empty?
+
+        # Worker numbers and pids differ between otherwise identical deaths.
+        group = reasons.group_by { |reason| reason.delete("0-9") }.values.max_by(&:size)
+        "\n  most common cause (#{group.size} of #{errored.size}): #{group.first}"
+      end
+
+      # A reason can carry invalid bytes, terminal escapes or a huge line,
+      # and this runs on the way to the exit code: scrub, escape controls and
+      # cap before anything groups or prints it, and never raise.
+      def self.first_line(reason)
+        text = Text.utf8(reason.to_s).lines.map(&:strip).find { |line| !line.empty? }.to_s
+        text = Text.display_safe(text.gsub(/\e\[[0-9;]*[A-Za-z]/, ""))
+        text.length > LIMIT ? "#{text[0, LIMIT]}..." : text
+      rescue StandardError
+        reason.to_s.dump[0, LIMIT]
+      end
+    end
+  end
+end