saboteur 0.6.0 → 0.8.0

data/exe/saboteur

@@ -2,15 +2,42 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-# Line coverage must be set up before any target code loads, so it happens
-# first. For `run` it also counts from here: what executes while the app and
+# Coverage comes first because it only measures files loaded after it -
+# the crash reporter must stay measurable - and it loads inside the same
+# guarded begin as the reporter: every later failure, even while the CLI
+# is being required, gets the full report (the bounded one-liner, the log
+# file, the --verbose backtrace and agent JSON when the CLI loaded far
+# enough). If even the reporter cannot load, a bare normalized one-liner
+# (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
+
+  require "saboteur/crash_report"
+rescue LoadError, StandardError => e
+  message = e.message.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?").gsub(/\s+/, " ").strip
+  message = "#{message[0...160]}..." if message.length > 160
+  warn "saboteur: internal error (#{e.class}: #{message}) - please report it: " \
+       "https://github.com/vamsipavanmahesh/saboteur/issues"
+  exit 3
+end
+
+# For `run` coverage counts from here: what executes while the app and
 # spec files load is how ran-at-load mutants are told apart from uncovered
 # 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).
-require "coverage"
-Coverage.setup(lines: true, methods: true, branches: true) if Coverage.state == :idle
-Coverage.resume if ARGV.first == "run" && Coverage.state == :suspended
+begin
+  Coverage.resume if ARGV.first == "run" && Coverage.state == :suspended
 
-require "saboteur/cli"
+  require "saboteur/cli"
 
-exit Saboteur::CLI.new(ARGV).call
+  exit Saboteur::CLI.new(ARGV).call
+rescue LoadError, StandardError => e
+  # Agent mode is visible in the raw arguments; the CLI may never have
+  # loaded, so this scan must not depend on it.
+  agent = ARGV.include?("--agent") || ARGV.include?("--format=agent") ||
+          ARGV.each_cons(2).any? { |flag, value| flag == "--format" && value == "agent" }
+  exit Saboteur::CrashReport.call(e, verbose: ARGV.include?("--verbose"), agent: agent,
+                                     err: $stderr, out: $stdout,
+                                     log_path: File.join(Dir.pwd, ".saboteur", "internal-error.log"))
+end

data/lib/saboteur/baseline/workflow.rb

@@ -4,6 +4,7 @@
 require_relative "acceptance"
 require_relative "comparison"
 require_relative "../engine"
+require_relative "../text"
 
 module Saboteur
   module Baseline
@@ -70,7 +71,7 @@ module Saboteur
 
         bytes = File.read(path)
         @baseline_digest = Digest::SHA256.hexdigest(bytes)
-        manifest = Manifest.new(JSON.parse(bytes))
+        manifest = Manifest.new(JSON.parse(Text.utf8_strict(bytes)))
         metadata = manifest.to_h.fetch("metadata")
         candidates = manifest.candidates.values
         restored = metadata.slice("snapshot", "subjects", "complete", "issues").merge(

data/lib/saboteur/baseline_health.rb

@@ -4,6 +4,8 @@
 require "json"
 require "tempfile"
 
+require_relative "text"
+
 module Saboteur
   # Two fresh supervised children check the full suite without changing methods
   # or writing caches. This samples stability; it cannot prove absence of flakes.
@@ -49,8 +51,9 @@ module Saboteur
 
     def check_run(number, expected)
       Tempfile.create("saboteur-baseline") do |log|
-        result = @supervisor.run(timeout: @config["baseline_timeout"]) { |writer| record(writer, log.path) }
-        data = read_result(result, number)
+        result = @supervisor.run(timeout: @config["baseline_timeout"],
+                                 label: "baseline child died during setup/run") { |writer| record(writer, log.path) }
+        data = read_result(result, number, log)
         verify_execution(data, number, expected)
         raise Error, "baseline run #{number} left processes running; fix suite cleanup" if result.leftover_pids.any?
 
@@ -64,9 +67,12 @@ module Saboteur
       raise Error, "baseline check failed: #{e.class}: #{e.message}; check suite hooks and setup"
     end
 
-    def read_result(result, number)
+    def read_result(result, number, log = nil)
       raise Error, "baseline run #{number} stopped: #{result.detail}" if result.stopped_by
-      raise Error, "baseline run #{number} exited without a result; check suite boot and exits" if result.payload.empty?
+      if result.payload.empty?
+        raise Error, "baseline child died during setup/run: baseline run #{number} exited without a " \
+                     "result#{exit_detail(result.exit_status)}; check suite boot and exits#{log_tail(log)}"
+      end
       if result.child_failed?
         raise Error, "baseline run #{number} exited unsuccessfully; fix suite cleanup and exit handlers"
       end
@@ -77,6 +83,30 @@ module Saboteur
       data
     end
 
+    # The child's own output when it died without answering: the redirect
+    # puts its last words in this log, not on the terminal (#289). Bounded
+    # (about 2 KB, 20 lines) and scrubbed before it joins the error. Read
+    # through the parent's open handle, and strictly best-effort: a dead
+    # handle must never mask the real exit or signal error.
+    def log_tail(log)
+      return "" unless log
+
+      log.seek([log.size - 2048, 0].max)
+      tail = Text.utf8(log.read(2048).to_s).lines.last(20).map(&:chomp).join(" / ")
+      tail.empty? ? "" : "; child log tail: #{tail}"
+    rescue SystemCallError, IOError
+      ""
+    end
+
+    # The child's ending when the supervisor reaped one ("exit 1",
+    # "signal SIGKILL", ...): an empty result's cause is usually there (#255).
+    def exit_detail(status)
+      return "" unless status.is_a?(Process::Status)
+      return " (signal #{Signal.signame(status.termsig)})" if status.signaled?
+
+      " (exit #{status.exitstatus})"
+    end
+
     def verify_execution(data, number, expected)
       unless data["passed"] == true
         raise Error, "baseline run #{number} failed: #{data['error'] || 'fix the unchanged suite'}"
@@ -93,8 +123,12 @@ module Saboteur
         exception = example.execution_result.exception
         next unless exception
 
-        message = exception.message.to_s.lines.map(&:strip).find { |line| !line.empty? }.to_s[0, 200]
-        "#{example.id}: #{example.full_description.to_s[0, 200]}: #{message}"
+        # Exception text and example names can arrive locale-tagged or as
+        # raw path bytes (e.g. Errno::EILSEQ): scrub each field before any
+        # strip, truncation or interpolation - all three raise on bad tags.
+        # This detail ships in a JSON payload, so it must be valid UTF-8.
+        message = Text.utf8(exception.message.to_s).lines.map(&:strip).find { |line| !line.empty? }.to_s[0, 200]
+        "#{Text.utf8(example.id.to_s)}: #{Text.utf8(example.full_description.to_s)[0, 200]}: #{message}"
       end.first(5).join("; ")
     end
 

data/lib/saboteur/cli/exit_status.rb

@@ -8,7 +8,28 @@ 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, so fall
+      # back to no log.
+      def crash_log_path
+        dir = config.path("cache_dir")
+        dir && File.join(dir, CrashReport::LOG_NAME)
+      rescue StandardError
+        nil
+      end
+
       def exit_code(report)
+        return EXIT_BUDGET if budget_exhausted?(report)
+
+        return EXIT_TOOL if untested_partial?(report)
+
+        return EXIT_TOOL if unverifiable_scope?(report)
+
         return EXIT_TOOL if mostly_errored?(report)
 
         return EXIT_TOOL if incomplete_under_threshold?(report)
@@ -16,6 +37,50 @@ module Saboteur
         failed_quality_gate?(report) || gates.failed?(report, @err) ? EXIT_SURVIVORS : EXIT_OK
       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.
+      def budget_exhausted?(report)
+        report.early_stop&.reason == "max_duration" && !config["max_duration_ok"]
+      end
+
+      # A run stopped before any mutant was tested has no verdict to fall
+      # back on: --max-duration-ok must not turn it green. Unverified
+      # results are not tested verdicts, so an unverified-only stop has no
+      # score either (#296). Exit 3, like the other incomplete shapes.
+      def untested_partial?(report)
+        return false unless report.early_stop && report.score_breakdown.tested.zero?
+
+        @err.puts("saboteur: the run stopped before any mutant was tested, so there is no score to judge")
+        true
+      end
+
+      # A run that verified none of the change under review - every
+      # subject skipped (refinements, no coverage, ..., #574) or every
+      # mutant unreachable (a suite re-loading mutated files, #597) -
+      # 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("saboteur: #{subject.id} was skipped (#{reason}), so the change under test was not verified")
+          end
+          return true
+        end
+        return false unless unverifiable_unreachable?(report)
+
+        @err.puts("saboteur: all mutants ran unreachable, so the change under test was not verified")
+        true
+      end
+
+      def unverifiable_review?(report)
+        report.review? && report.subjects.any? &&
+          report.subjects.all? { |subject| report.skipped_subjects.key?(subject) }
+      end
+
+      def unverifiable_unreachable?(report)
+        report.executed.any? && report.executed.all? { |result| result.status == :unreachable }
+      end
+
       def gates = (@gates ||= Gates.new(config))
 
       def mostly_errored?(report)
@@ -33,9 +98,11 @@ module Saboteur
       # incomplete run that mostly errored keeps its distinct cause, so the
       # harness rule means the same thing in both modes.
       def agent_exit_cause(report, payload)
+        return "budgetExhausted" if budget_exhausted?(report)
+
         case payload[:verdict]
         when "clean" then "ok"
-        when "survivors" then report.early_stop ? "failFast" : "survivors"
+        when "survivors" then report.early_stop&.reason == "fail_fast" ? "failFast" : "survivors"
         else report.majority_errored? ? "errorMajority" : "incomplete"
         end
       end
@@ -45,22 +112,31 @@ module Saboteur
       def exit_cause(report, code)
         case code
         when EXIT_OK then "ok"
+        when EXIT_BUDGET then "budgetExhausted"
         when EXIT_SURVIVORS then survivors_cause(report)
-        else report.majority_errored? ? "errorMajority" : "incompleteUnderThreshold"
+        else
+          if report.majority_errored?
+            "errorMajority"
+          elsif unverifiable_review?(report) || unverifiable_unreachable?(report) ||
+                (report.early_stop && report.score_breakdown.tested.zero?)
+            "incomplete"
+          else
+            "incompleteUnderThreshold"
+          end
         end
       end
 
       # A run stopped by --fail-fast always exits 1: it stopped on a survivor, and
       # its score covers only the subjects that ran, so no threshold can pass it.
       def survivors_cause(report)
-        return "failFast" if report.early_stop
+        return "failFast" if report.early_stop&.reason == "fail_fast"
 
         gates.cause || (config["threshold"].nil? ? "survivors" : "belowThreshold")
       end
 
       # With --threshold the score decides; without it any unignored survivor does.
       def failed_quality_gate?(report)
-        return true if report.early_stop
+        return true if report.early_stop&.reason == "fail_fast"
 
         threshold = config["threshold"]
         return report.unignored_survivors.any? if threshold.nil?

data/lib/saboteur/cli/help_options.rb

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The option map `saboteur help` prints per command. run, pr and audit
+    # share the run parser: the presets take every run option.
+    module HelpOptions
+      def option_lines
+        run = parser.summarize
+        { "run" => run, "pr" => run, "audit" => run, "doctor" => doctor_parser.summarize,
+          "baseline" => baseline_parser.summarize, "badge" => badge_parser.summarize,
+          "trend" => trend_parser.summarize }
+      end
+    end
+  end
+end

data/lib/saboteur/cli/history_command.rb

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "../reporter/history_reader"
+
+module Saboteur
+  class CLI
+    # `saboteur badge` and `saboteur trend` (#474): a local README badge and
+    # a trend read-out over the opt-in score history, no hosted service.
+    module HistoryCommand
+      DEFAULT_HIGH = 80.0
+      DEFAULT_LOW = 60.0
+
+      def badge_parser
+        OptionParser.new do |opts|
+          opts.banner = "Usage: saboteur badge [--history PATH] [--output PATH] [--mark-partial] " \
+                        "[--high PERCENT] [--low PERCENT]"
+          opts.on("--history PATH", "Score history JSONL (default: c.score_history)") { |v| @history_path = v }
+          opts.on("--output PATH", "Badge JSON destination (default: stdout)") { |v| @output = v }
+          opts.on("--mark-partial", "Badge an incomplete run, labeled as partial") { @mark_partial = true }
+          opts.on("--high PERCENT", Float, "brightgreen at or above (default #{DEFAULT_HIGH.to_i})") { |v| @high = v }
+          opts.on("--low PERCENT", Float, "yellow at or above (default #{DEFAULT_LOW.to_i})") { |v| @low = v }
+        end
+      end
+
+      def trend_parser
+        OptionParser.new do |opts|
+          opts.banner = "Usage: saboteur trend [--history PATH]"
+          opts.on("--history PATH", "Score history JSONL (default: c.score_history)") { |v| @history_path = v }
+        end
+      end
+
+      private
+
+      def history_command(command) = command == "badge" ? badge : trend
+
+      def badge
+        badge_parser.parse!(@argv)
+        raise UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
+
+        write_badge(badge_payload(read_history.last))
+        EXIT_OK
+      rescue ConfigError, Error, SystemCallError => e
+        history_failure(e)
+      end
+
+      def trend
+        trend_parser.parse!(@argv)
+        raise UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
+
+        print_trend(latest_pair)
+        EXIT_OK
+      rescue ConfigError, Error, SystemCallError => e
+        history_failure(e)
+      end
+
+      def history_failure(error)
+        @err.puts("saboteur: #{error.message}")
+        error.is_a?(ConfigError) ? EXIT_USAGE : EXIT_TOOL
+      end
+
+      def latest_pair
+        records = read_history
+        current = records.last
+        [records[0...-1].reverse.find { |record| Reporter::HistoryReader.comparable?(record, current) }, current]
+      end
+
+      def read_history
+        records = Reporter::HistoryReader.read(history_path)
+        if records.empty?
+          raise Error,
+                "score history is empty - record it first by running saboteur with c.score_history set"
+        end
+
+        records
+      end
+
+      def history_path
+        @history_path ||= config.path("score_history")
+        @history_path or raise UsageError, "no score history: pass --history PATH or set c.score_history"
+      rescue ConfigError
+        raise UsageError, "no score history: pass --history PATH or set c.score_history"
+      end
+
+      def badge_payload(record)
+        partial = record["incomplete"].any?
+        if partial && !@mark_partial
+          raise Error, "the latest score history record is an incomplete run " \
+                       "(#{record['incomplete'].map(&:inspect).join(', ')}) - " \
+                       "badge evidence needs a complete run, or pass --mark-partial to label it"
+        end
+        score = record["coveredScore"]
+        raise Error, "the latest score history record has no tested mutants" if score.nil?
+
+        { schemaVersion: 1, label: partial ? "mutation score (partial)" : "mutation score",
+          message: format("%.1f%%", score * 100), color: badge_color(score) }
+      end
+
+      def write_badge(payload)
+        json = "#{JSON.generate(payload)}\n"
+        return @out.print(json) unless @output
+
+        File.write(@output, json)
+        @out.puts(@output)
+      end
+
+      def badge_color(score)
+        percent = score * 100
+        return "brightgreen" if percent >= (@high || DEFAULT_HIGH)
+        return "yellow" if percent >= (@low || DEFAULT_LOW)
+
+        "red"
+      end
+
+      def print_trend((previous, current))
+        ([previous].compact + [current]).each { |record| @out.puts(trend_line(record)) }
+        unless previous && previous["coveredScore"] && current["coveredScore"]
+          return @out.puts("score history: no comparable earlier record (different selection/inventory, " \
+                           "operator policy or an incomplete run)")
+        end
+
+        delta = (current["coveredScore"] - previous["coveredScore"]) * 100
+        @out.puts(format("covered score change %<delta>+.2f percentage points since %<since>s " \
+                         "(same configured selection)", delta: delta, since: previous["date"]))
+      end
+
+      def trend_line(record)
+        suffix = record["incomplete"].empty? ? "" : " (incomplete)"
+        score = record["coveredScore"]
+        "#{record['date']} #{record['commit']&.slice(0, 8) || '-'} " \
+          "#{score.nil? ? 'no tested mutants' : format('%.1f%%', score * 100)}#{suffix}"
+      end
+    end
+  end
+end

data/lib/saboteur/cli/presets.rb

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Opinionated bundles (#244): pr is the fast changed-lines loop (one
+    # baseline check, a 10-minute budget that fails an incomplete run),
+    # audit is the whole project with both reports. Preset flags go first,
+    # so an explicit flag after them wins on the usual last-flag rule.
+    module Presets
+      PRESETS = {
+        "pr" => %w[--baseline-passes 1 --max-duration 10m],
+        "audit" => %w[--all --operators all --baseline-passes 2 --json .saboteur/audit-report.json
+                      --html .saboteur/audit-report.html]
+      }.freeze
+
+      private
+
+      def preset_or_usage_error(command)
+        PRESETS.key?(command) ? preset(command) : usage_error
+      end
+
+      def preset(name)
+        flags = PRESETS.fetch(name).dup
+        if name == "pr"
+          ref = @argv.first.nil? || @argv.first.start_with?("-") ? "main" : @argv.shift
+          flags += ["--since", ref]
+        end
+        # An explicit scope beats the injected whole-suite --all, which
+        # would otherwise reject the combination: named tests, and the
+        # deprecated inference alias (#245).
+        explicit_scope = @argv.any? { |arg| arg == "--test" || arg.start_with?("--test=") || arg == "--guess-tests" }
+        flags.delete("--all") if explicit_scope
+        @err.puts("saboteur: preset '#{name}': #{flags.join(' ')} (explicit flags override)")
+        @argv = flags + @argv
+        run_command
+      end
+    end
+  end
+end

data/lib/saboteur/cli/run_budget_options.rb

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The run's clock and repeatability switches: seed, baseline check count
+    # (#55) and the wall-clock budget (#245). Grouped so the option table in
+    # the CLI stays under the house size caps.
+    module RunBudgetOptions
+      private
+
+      def add_run_budget_options(opts)
+        opts.on("--seed N", Integer, "Seed for Ruby's random numbers in every test run (default 1)") do |v|
+          set(:seed, v)
+        end
+        opts.on("--baseline-passes N", Integer, "Unchanged-suite checks (default 2)") { |v| set(:baseline_passes, v) }
+        opts.on("--max-duration DURATION", "Wall-clock budget for the whole run, e.g. 10m; exit 4 when spent") do |v|
+          set(:max_duration, parse_duration(v))
+        end
+        opts.on("--[no-]max-duration-ok", "An exhausted --max-duration budget does not fail the run") do |v|
+          set(:max_duration_ok, v)
+        end
+      end
+
+      # "10m" -> 600.0; bare numbers are seconds. A bad value is a usage error.
+      def parse_duration(value)
+        match = /\A(?<amount>\d+(?:\.\d+)?)(?<unit>[smh])?\z/.match(value.to_s.strip)
+        unless match
+          raise ConfigError,
+                "invalid --max-duration #{value.inspect}: use seconds or an s/m/h suffix, e.g. 10m"
+        end
+
+        match[:amount].to_f * { "s" => 1, "m" => 60, "h" => 3600, nil => 1 }.fetch(match[:unit])
+      end
+    end
+  end
+end

data/lib/saboteur/cli/run_reporting.rb

@@ -10,9 +10,10 @@ module Saboteur
     module RunReporting
       private
 
-      def text_run(report)
+      def text_run(report, engine)
         @err.puts
-        Reporter::Terminal.new(@out, verbose: @verbose || false, color: @color || :auto).call(report)
+        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]
         code = exit_code(report)
         # The JSON carries the exit cause an outer harness trusts, so it is
@@ -50,7 +51,65 @@ module Saboteur
         validate_history
         arguments = { err: @err }
         arguments[:digest] = options[:id] if options[:id]
-        agent? ? agent_run(arguments) : text_run(Engine.new(config, **arguments).call)
+        return agent_run(arguments) if agent?
+
+        # Text mode only: the engine prints a per-subject marks line when
+        # --verbose is on (#262); --agent output stays as it is.
+        engine = Engine.new(config, **arguments, verbose: @verbose || false)
+        text_run(engine.call, engine)
+      end
+
+      # The full replay command for a survivor digest: this run's own
+      # 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.
+      def survivor_replay_command(report, engine)
+        lambda do |digest|
+          tree = WorkingTree.new(config.root, ignored: config.output_paths).state
+          Reporter::Agent::Commands.replay(agent_provenance(report, tree, engine), digest, capped: false)
+        end
+      end
+
+      # Writes the JSON report and returns its path, or nil when none is configured.
+      #
+      # An explicitly requested JSON report (--json, c.json_report) is the
+      # completion evidence an outer harness trusts: a failed write fails
+      # the run (exit 3), because a warning with exit 0 could leave a stale
+      # or partial file at the path and present old results as this run's.
+      # The default .saboteur/report.json is best-effort like the HTML
+      # report and the score history (#296).
+      def write_json(report, cause)
+        path = config.path("json_report")
+        return unless path
+
+        Reporter::Stryker.new(path).call(report, exit_cause: cause)
+        path
+      rescue SystemCallError, IOError => e
+        if config.explicit?("json_report")
+          raise Error, "could not write the JSON report to #{path}: #{e.message} - " \
+                       "any file at that path may be stale or incomplete"
+        end
+
+        warn_report_write_failure("JSON report", path, e)
+      end
+
+      def write_html(report)
+        path = config.path("html_report")
+        return unless path
+
+        Reporter::Html.new(path).call(report)
+        path
+      rescue SystemCallError, IOError => e
+        warn_report_write_failure("HTML report", path, e)
+      end
+
+      # An auxiliary report artifact that cannot be written - the tree is
+      # read-only inside a sandboxed child, as in the dogfood's nested runs
+      # (#296) - is a warning, not a run failure: the exit code belongs to
+      # the results. The JSON report is not auxiliary; see write_json.
+      def warn_report_write_failure(what, path, error)
+        @err.puts "saboteur: could not write the #{what} to #{path} (#{error.message}); continuing without it"
+        nil
       end
 
       def validate_history
@@ -67,8 +126,18 @@ module Saboteur
 
         tree = WorkingTree.new(config.root, ignored: config.output_paths).state
         scope = config.selection_settings.except("json_report", "html_report", "score_history", "cache_dir")
-        message = Reporter::ScoreHistory.new(path).append(report, head: tree.head, scope: scope)
-        @err.puts("saboteur: #{message}")
+        # 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
+        # error. Only the write's IO failures are soft: validation,
+        # integrity, record-size and lock failures (Saboteur::Error) stay
+        # hard, because they say the history is unusable, not unwritable.
+        message = begin
+          Reporter::ScoreHistory.new(path).append(report, head: tree.head, scope: scope)
+        rescue SystemCallError, IOError => e
+          warn_report_write_failure("score history", path, e)
+        end
+        @err.puts("saboteur: #{message}") if message
       end
     end
   end

data/lib/saboteur/cli/selection_options.rb

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The run's subject-selection flags: operator sets, single-mutant replay,
+    # --since scoping, --dry-run, the flaky-check confirmation rerun (#476)
+    # and explicit --subject filters. Grouped so the CLI stays under the
+    # house size caps.
+    module SelectionOptions
+      private
+
+      def define_selection_options(opts)
+        opts.on("--operators NAMES", Array, "Choose operator names (default: all)") do |v|
+          set(:operators, v)
+        end
+        opts.on("--exclude-operators NAMES", Array, "Exclude operator names from the selected set") do |v|
+          set(:exclude_operators, v)
+        end
+        opts.on("--list-operators", "List operator names and descriptions") { set(:list_operators, true) }
+        opts.on("--dry-run", "Preview mutants without boot, tests, forks or report writes") { set(:dry_run, true) }
+        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 }
+        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) }
+      end
+    end
+  end
+end

data/lib/saboteur/cli/shard_options.rb

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Validates the deterministic candidate-shard selection before the target boots.
+    module ShardOptions
+      private
+
+      def validate_shard_options
+        raise UsageError, "--id cannot be combined with --shard" if options[:id] && config["shard"]
+
+        Engine::Shard.parse(config["shard"]) if config["shard"]
+      end
+    end
+  end
+end