saboteur 0.12.1 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9537980fed0394bdadcbd64d8e637e55cfb42925b5673d2ee30e6f0b18bb13e
-  data.tar.gz: a628132a21155e240bc856c99707f46323f280929344048be98a746fa74d1c9b
+  metadata.gz: 19bac537a82f6aa32ade9a7a1955cd793793d5a95b026dc56274c7c97560cfa6
+  data.tar.gz: 40086d139cbb82e418c9b7de5aa31b2aedd19eeb61ae238ba01f80c0e3f0d5b4
 SHA512:
-  metadata.gz: c96be31b305e173850739c426f5343fb6a24b416cb5f923b30cfea4a8764fb0c9dd3eeeb5dc8b00af132e16267e8e4135ea84d2d5669b38e35433323e94c072c
-  data.tar.gz: 9763cf728f40ad70a714665bc4cdf09ce0a9d516d7da9101bb137f60cdb378a5715d321d8b71d725ac635736b167a9ce6ec3b8c5e99632ef1f204cea49ad3e94
+  metadata.gz: 1dda55357cc1866e39f052b3b69424e6dde81ec551b695822e35e58a5ec65fe00b0e795b650338c12e2a2869e4a046f3a6e0839742e86bb3bd7ae52db809e124
+  data.tar.gz: f094725207c45c6b5c73d848790f2a6d8a91e849dcd281eabf616c6de414fbf6f9f9f589c7a15c0d6e15c72d1e21971be4a2edc19802691bc2c508b965fe99e9

data/CHANGELOG.md

@@ -6,6 +6,92 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.12.3] - 2026-10-22
+
+### Added
+
+- Survivors are labeled `input_gap` or `assertion_gap` from the value the
+  mutated expression actually produced (side-effect-free sites only).
+  `input_gap` means the tests never gave the expression an input where its
+  value differs, or no test reached it. `assertion_gap` means the value
+  changed and the tests still passed. The JSON report gains `valueDiffed`
+  and `gapKind` fields (#1290, #1305, #1306, #1307).
+
+### Changed
+
+- The cache stores the observed value with each verdict (cache format 2),
+  so cached results from before this release are rebuilt once on the next
+  run (#1290, #1307).
+
+## [0.12.2] - 2026-10-22
+
+### Added
+
+- A scoped run (`--since`, `--subject`, or the default spec inference)
+  confirms its survivors against the whole-suite coverage map when one
+  exists. Each survivor gets one budgeted confirmation run of the covering
+  specs the run did not load. A mutant those specs kill becomes killed,
+  credited to the killing test in the JSON report, and counts in the score
+  and exit code. A survivor whose covering specs could not be run is listed
+  as unconfirmed, left out of the score and exit code, and ranked below
+  confirmed survivors. A map that is older than the tree and says nothing
+  about a survivor's lines keeps that survivor counted, with one line
+  naming how many. A covering spec outside the project root is never
+  loaded (#1286, #1304).
+- `--color` and `--no-color` work on every text command, and a usage error
+  names the command that failed instead of showing `saboteur run` usage
+  (#1288, #1301).
+
+### Changed
+
+- Only `saboteur run --all` records the whole-suite coverage map. A run
+  built from inferred specs no longer claims to be whole-suite. Without a
+  whole-suite map a scoped run prints one line saying survivors are
+  unconfirmed and how to build the map, and each survivor block says its
+  covering list is this run's selection only (#1286, #1300).
+- A statement's gap label comes from all of its surviving mutants with a
+  fixed precedence: result unchecked, error path, branch, boundary,
+  effect, number, instead of from the first mutant (#1289, #1297).
+- `baseline propose` records a mutant on a line no test runs as a gap
+  instead of an unexecuted blocker, so a tested method with one untested
+  line can still be proposed (#1287, #1299).
+- A config-less Rails app's default `app/**/*.rb` include counts as a
+  full run, so the stale ignore entry warning fires there (#1255, #1296).
+- `--quiet` no longer prints the missing-config notice, the coverage cache
+  miss or the map-build lines (#1264, #1293).
+- Output polish: the run header names the `--subject` scope, the
+  no-spec note reads in the singular, untested subjects are named once
+  under "Not scored", and the replay example uses the top-ranked
+  survivor (#1291, #1298).
+- Report test ids in `killedBy`, `coveredBy` and `testFiles` are numbered
+  by sorted test name, so the same tests keep the same ids across runs
+  (#1282, #1295). Covering tests are ordered by millisecond buckets, so
+  kill attribution is stable (#1274, #1283).
+
+### Fixed
+
+- An empty `--since` diff whose mutants all failed generation no longer
+  exits 0 under `--threshold`, and `--ignore-empty` no longer fails a run
+  without `--since` (#1265, #1266, #1284).
+- `saboteur survivors` no longer drops an unknown keyword silently
+  (#1267, #1285).
+
+### Corrected
+
+- 0.12.0 said uncovered survivors are labeled `input_gap`, "separate from
+  assertion gaps" (#1254, #1157). Only `input_gap` exists, meaning no test
+  ran the mutant. There is no assertion-gap label yet (#1064).
+- 0.11.2 said survivor blocks consult the whole-suite coverage map,
+  "ending false survivors from diff-scoped runs" (#1252). That change
+  only affects which covering tests a block lists. A survivor whose real
+  test sits in a spec file saboteur did not select can still be reported
+  as a survivor; see "Know the limits" in the README.
+
+### Tests
+
+- The worker pool and supervisor specs assert concurrency with a barrier
+  instead of a wall-clock bound (#1302, #1303).
+
 ## [0.12.1] - 2026-10-22
 
 ### Changed

data/README.md

@@ -80,15 +80,21 @@ tree refuses with exit 2 and points at the generator. Engine gem with
   assertion, 1 by a crash`), and an error-dominated run prints
   `Score: n/a` instead of a number you would misread.
 - 🔍 **Survivors you can act on.** Survivors group per statement with a
-  triage label (`likely_equivalent`, `arid`, `tool_limit`, or a gap kind) and their
+  triage label (`likely_equivalent`, `arid`, `tool_limit`, `input_gap` (the tests
+  never gave the mutated expression an input where its value differs, or no
+  test reached it), `assertion_gap` (the value changed and the tests still
+  passed), or a gap kind) and their
   covering tests - split into the tests that ran against the mutant and
   the ones that never did. `saboteur survivors` browses them read-only:
   one digest shows the full diff and the exact replay command.
 - 🧪 **Flakiness contained.** `--flaky-check survivors` re-runs each new
   survivor in a reordered confirmation pass; a verdict the rerun disagrees
   with becomes `unverified` and stays out of the score. With
-  `partial_coverage = "use"`, open survivors get one budgeted confirmation
-  run against the covering specs that never ran them.
+  `partial_coverage = "use"`, open
+  survivors get one budgeted confirmation run against the covering specs
+  that never ran them when the map is built from every spec (`--all`, no
+  `--test`, one coverage part, cache on). Default inferred-spec runs, `pr`
+  included, skip it.
 - 📊 **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 survivors as review comments on your PR diff lines.
@@ -127,6 +133,15 @@ tree refuses with exit 2 and points at the generator. Engine gem with
 - A survivor is review evidence, not proof of a bug in your tests. It can
   be a missing test, an equivalent change, a flaky test, or a limit of
   the tool. Read it before you write a test for it.
+- A survivor can be false when the test that kills it lives in a spec
+  file saboteur did not select. Runs without `--test` pick specs by file
+  name and by the constants they read, so a test in a differently named
+  spec (say `spec/integration/flow_spec.rb` for `lib/ledger/router.rb`)
+  may never run against the mutant, and the "covered by ... ran, still
+  passed" lines list the specs that ran, plus any others marked "not run
+  here". If you know
+  another spec exercises the code, run again with `--test` naming it
+  before you trust the survivor.
 - `--since` and `--incremental` are iteration aids. Run the whole project
   on main and before a release.
 - Sandboxing varies by platform and network access is never restricted.

data/lib/saboteur/baseline/command.rb

@@ -21,6 +21,7 @@ module Saboteur
           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 }
+          define_color_options(opts)
         end
       end
 
@@ -86,7 +87,11 @@ module Saboteur
         survivors = payload.fetch("survivors")
         @out.puts("  matched mutants: #{payload.fetch('candidates')} " \
                   "(#{plural(survivors, 'survivor')} to reason about)")
-        gaps = payload.fetch("gaps", [])
+        uncovered, gaps = payload.fetch("gaps", []).partition { |gap| gap.start_with?("no_coverage:") }
+        unless uncovered.empty?
+          @out.puts("  proposed with #{plural(uncovered.size, 'mutant')} on lines no test runs - " \
+                    "the baseline cannot speak for them")
+        end
         unless gaps.empty?
           names = gaps.map { |gap| gap.sub(/\A(subject_skipped|omitted):/, "") }
           @out.puts("  proposed with #{plural(names.size, 'untested subject')}: #{names.join(', ')} - " \

data/lib/saboteur/baseline/comparison.rb

@@ -38,7 +38,10 @@ module Saboteur
       def classify(baseline, current)
         categories = CATEGORY_NAMES.to_h { |name| [name, []] }
         previous = baseline.fetch("accepted").to_h { |entry| [entry.fetch("id"), entry] }
+        uncovered = uncovered_ids(current)
         current.fetch("candidates").each do |entry|
+          next if uncovered.include?(entry.fetch("id"))
+
           accepted = previous.delete(entry.fetch("id"))
           name = category(entry, accepted)
           categories.fetch(name) << entry if name
@@ -48,6 +51,11 @@ module Saboteur
         categories
       end
 
+      # Mutants on lines no test runs are listed as gaps, never as errors.
+      def uncovered_ids(current)
+        Completeness.uncovered_ids(current.fetch("gaps", []))
+      end
+
       def category(entry, accepted)
         case entry.fetch("status")
         when "survived"

data/lib/saboteur/baseline/completeness.rb

@@ -7,17 +7,24 @@ module Saboteur
     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
+      # proposal. Everything else is a hard blocker. no_coverage: is a mutant
+      # on a line no test runs inside a tested subject (#1287).
+      SOFT_PREFIXES = %w[subject_skipped: omitted: no_coverage:].freeze
       attr_reader :issues
 
+      # The mutant ids named by no_coverage: gaps.
+      def self.uncovered_ids(gaps)
+        gaps.filter_map { |gap| gap.delete_prefix("no_coverage:") if gap.start_with?("no_coverage:") }
+      end
+
       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:)
+                     generation_issues:, uncovered: [])
         @issues = []
+        @uncovered = uncovered
         issues << "unchanged_suite_incomplete" unless stable_suite
         issues << "inputs_unverified" unless stable_inputs
         validate_inventory(planned, subjects)
@@ -66,7 +73,10 @@ module Saboteur
       def validate_results(results)
         results.each do |entry|
           status = entry.fetch("status")
-          issues << "unexecuted:#{entry.fetch('id')}:#{status}" unless EXECUTED.include?(status)
+          next if EXECUTED.include?(status)
+
+          id = entry.fetch("id")
+          issues << (@uncovered.include?(id) ? "no_coverage:#{id}" : "unexecuted:#{id}:#{status}")
         end
       end
     end

data/lib/saboteur/baseline/evidence.rb

@@ -47,11 +47,18 @@ module Saboteur
           entry.slice("id", "context").merge("reason" => reasons)
         end
         { "format" => Manifest::FORMAT, "identity_version" => Identity::VERSION,
-          "metadata" => metadata, "candidates" => document.fetch("candidates"), "accepted" => accepted }
+          "metadata" => metadata, "candidates" => executed_candidates, "accepted" => accepted }
       end
 
       private
 
+      # A mutant on a line no test runs is a gap in the proposal's issues,
+      # not a candidate: the baseline has no verdict to compare it against.
+      def executed_candidates
+        uncovered = Completeness.uncovered_ids(document.fetch("gaps"))
+        document.fetch("candidates").reject { |entry| uncovered.include?(entry.fetch("id")) }
+      end
+
       def array!(value, name)
         raise ConfigError, "baseline #{name}" unless value.is_a?(Array)
       end

data/lib/saboteur/baseline/run_evidence.rb

@@ -43,6 +43,7 @@ module Saboteur
         errors = generation_issues(generation, results) + context_issues(observed) + discovery_issues(discovery)
         suppressions = suppression_scope(inline_suppressions)
         errors += suppression_issues(suppressions)
+        @uncovered = uncovered_ids(results)
         completeness = assess(observed, stable_suite, skipped_subjects, omissions, errors)
         document = { "compatibility" => compatibility, "snapshot" => @snapshot.to_h, "subjects" => @subjects,
                      "candidates" => observed, "planned" => @planned,
@@ -83,13 +84,21 @@ module Saboteur
         end
       end
 
+      # Mutants skipped only because no test runs their line.
+      def uncovered_ids(results)
+        uncovered = results.select { |result| result.reason&.start_with?("no coverage") }
+        uncovered.map do |result|
+          Identity.new(subject: result.subject, mutation: result.mutation, root: @root).entry.fetch("id")
+        end
+      end
+
       def assess(observed, stable_suite, skipped_subjects, omissions, errors)
         skipped = skipped_subjects.map { |subject, reason| "#{subject.id}:#{reason}" }
         Completeness.new(planned: @planned.map { |entry| entry.fetch("id") }, results: observed,
                          subjects: @subjects, stable_suite: stable_suite,
                          stable_inputs: @fingerprint.verify(@snapshot).unchanged, skipped_subjects: skipped,
                          omitted: omissions.map { |entry| "#{entry.subject}:#{entry.count}" },
-                         generation_issues: errors)
+                         generation_issues: errors, uncovered: @uncovered)
       end
 
       def compatibility

data/lib/saboteur/baseline/workflow.rb

@@ -13,6 +13,8 @@ module Saboteur
     # Opt-in orchestration: every check/proposal runs fresh; acceptance only
     # edits reasons after verifying private execution evidence and current inputs.
     class Workflow
+      UNEXECUTED = /\Aunexecuted:([0-9a-f]{64}):(\w+)\z/
+
       def initialize(config:, err: $stderr)
         @config = config
         @err = err
@@ -50,20 +52,30 @@ module Saboteur
           [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
+        advise_unexecuted(blockers, by_id)
         raise Error, "baseline proposal needs a proposable run"
       end
 
+      # Narrowing include cannot add line coverage, so a blocker whose only
+      # cause is no coverage gets the specs advice alone.
+      def advise_unexecuted(blockers, by_id)
+        unexecuted = blockers.grep(/\Aunexecuted:/)
+        return if unexecuted.empty?
+
+        results = unexecuted.map { |issue| by_id[UNEXECUTED.match(issue)&.[](1)] }
+        coverage_only = results.all? { |result| result&.reason&.start_with?("no coverage") }
+        advice = coverage_only ? "specs" : "specs or narrow include"
+        @err.puts("saboteur: cover the skipped code with #{advice}, then propose again")
+      end
+
       def describe_blocker(issue, by_id)
-        match = /\Aunexecuted:([0-9a-f]{64}):(\w+)\z/.match(issue)
+        match = UNEXECUTED.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})"
+        "unexecuted:#{result.digest}:#{match[2]} (#{detail})"
       end
 
       def propose(proposal:, destination:, previous: nil)

data/lib/saboteur/cli/color_option.rb

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The colour switches every command that prints text accepts (#1288).
+    # --no-color stays as a deprecated alias for --color=never.
+    module ColorOption
+      private
+
+      def define_color_options(opts)
+        opts.on("--color [MODE]", %w[always never auto],
+                "Colour the text report: always, never or auto (default: auto)") do |value|
+          @color = (value || :always).to_sym
+        end
+        opts.on("--no-color", "Deprecated alias for --color=never") { @color = :never }
+      end
+
+      # Consume leading colour switches for commands that otherwise take
+      # positional arguments only (help, explain).
+      def consume_color_options
+        OptionParser.new { |opts| define_color_options(opts) }.order!(@argv)
+      end
+    end
+  end
+end

data/lib/saboteur/cli/doctor_command.rb

@@ -15,6 +15,7 @@ module Saboteur
           opts.on("--test PATH", "Spec file or directory for the suite runs; repeatable. Implies --suite") do |value|
             (options[:tests] ||= []) << value
           end
+          define_color_options(opts)
         end
       end
 

data/lib/saboteur/cli/exit_status.rb

@@ -32,13 +32,14 @@ module Saboteur
       # A --since diff that selected no mutants exits 0 with a plain note,
       # with or without --ignore-empty: a docs-only change has no score, so a
       # threshold must not fail it (#1142). Suppressed, omitted or
-      # undiscovered mutants still gate - the selection must be honestly
-      # empty, not just empty-handed.
+      # undiscovered mutants still gate, and so do mutants dropped because they
+      # did not parse (#1265) - the selection must be honestly empty, not just
+      # empty-handed.
       def empty_clean_diff?(report)
         return false unless config["since"] && report.results.empty?
         return false if unverifiable_scope?(report)
         return false unless report.omissions.empty? && report.inline_suppressions.empty? &&
-                            report.discovery_failures.empty?
+                            report.discovery_failures.empty? && report.invalid_mutations.zero?
 
         @err.puts("saboteur: no mutants in the diff - nothing to gate")
         true

data/lib/saboteur/cli/explain_command.rb

@@ -15,6 +15,7 @@ module Saboteur
       private
 
       def explain_command
+        consume_color_options
         name = @argv.shift
         raise UsageError, "usage: saboteur explain <operator>" if name.nil?
 
@@ -27,7 +28,7 @@ module Saboteur
           return EXIT_USAGE
         end
 
-        @out.puts(render_explain(entry, palette: Reporter::Palette.for(@out, mode: :auto)))
+        @out.puts(render_explain(entry, palette: Reporter::Palette.for(@out, mode: @color || :auto)))
         EXIT_OK
       rescue UsageError => e
         @err.puts("saboteur: #{e.message}")

data/lib/saboteur/cli/failure_output.rb

@@ -26,8 +26,19 @@ module Saboteur
 
       def usage_error(message = nil)
         @err.puts(Reporter::Palette.for(@err, mode: @color || :auto).paint(:fail, message)) if message
-        @err.puts(USAGE)
-        agent_failure(message || USAGE, EXIT_USAGE)
+        usage = command_usage
+        @err.puts(usage)
+        agent_failure(message || usage, EXIT_USAGE)
+      end
+
+      # The usage line of the command that failed, never run's for another
+      # command (#1288).
+      def command_usage
+        banner = { "doctor" => :doctor_parser, "baseline" => :baseline_parser, "badge" => :badge_parser,
+                   "trend" => :trend_parser }[@command]
+        return USAGE unless banner
+
+        "#{send(banner).banner}\nRun 'saboteur help #{@command}' for every option."
       end
 
       def agent? = @format == "agent"

data/lib/saboteur/cli/help_command.rb

@@ -8,6 +8,11 @@ module Saboteur
     module HelpCommand
       private
 
+      def help_command
+        consume_color_options
+        show_help(@argv.shift)
+      end
+
       def help_requested? = @argv.intersect?(%w[--help -h])
 
       def show_help(command_name)

data/lib/saboteur/cli/history_command.rb

@@ -20,6 +20,7 @@ module Saboteur
           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 }
+          define_color_options(opts)
         end
       end
 
@@ -27,6 +28,7 @@ module Saboteur
         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 }
+          define_color_options(opts)
         end
       end
 

data/lib/saboteur/cli/output_options.rb

@@ -29,10 +29,7 @@ module Saboteur
           @verbose = true
           set(:verbose, true)
         end
-        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
+        define_color_options(opts)
 
         # PR6: CI and pre-push output - the findings and the verdict only.
         opts.on("--quiet", "Text report: print only the findings and the verdict;",
@@ -46,7 +43,6 @@ module Saboteur
         # top three; --details restores a block for every finding.
         opts.on("--details", "Text report: full blocks for every finding;",
                 "default: one-line list plus the top 3 blocks") { set(:details, true) }
-        opts.on("--no-color", "Deprecated alias for --color=never") { @color = :never }
       end
     end
   end

data/lib/saboteur/cli/run_command.rb

@@ -22,7 +22,7 @@ module Saboteur
       # there is no init command - the Rails generator writes the config.
       def announce_missing_config_file(palette)
         # @format, not agent_requested?: parse! has already eaten --format.
-        return if @format == "agent" || config.config_file_present
+        return if @format == "agent" || options[:quiet] || config.config_file_present
 
         path = options[:config] || Config::FILE
         notice =

data/lib/saboteur/cli/run_reporting.rb

@@ -23,7 +23,7 @@ module Saboteur
                                      replay_command: survivor_replay_command(report, engine),
                                      all_mutants: options[:all_mutants] || false, details: options[:details] || false,
                                      exit_code: code, previous_score: previous_score, scope: scope_label,
-                                     whole_suite_map: whole_suite_map_for(engine),
+                                     whole_suite_map: whole_suite_map_for(engine, report),
                                      run_map: engine&.run_coverage_map,
                                      baseline_gate: (baseline_gate(report) if config["baseline"])).call(report)
         Reporter::Replay.new(@out).call(report) if options[:id]
@@ -40,14 +40,6 @@ module Saboteur
         code
       end
 
-      # No engine or no cache: no whole-suite map can exist, so the survivor
-      # block keeps its legacy covered-by line over an impossible build (review C1).
-      def whole_suite_map_for(engine)
-        return engine.whole_suite_coverage_map if engine&.whole_suite_map_lookup?
-
-        Reporter::SurvivorList::NO_WHOLE_SUITE_LOOKUP
-      end
-
       def agent_run(arguments)
         tree = WorkingTree.new(config.root, ignored: config.ignored_tree_paths).state
         # The machine path is exempt from the noise diet: quiet_start: false

data/lib/saboteur/cli/run_validation.rb

@@ -36,7 +36,6 @@ 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
 

data/lib/saboteur/cli/survivors_command.rb

@@ -49,7 +49,10 @@ module Saboteur
         if options[:show]
           @out.puts(browser.show(options[:show]))
         else
-          @out.puts(browser.list(**options.slice(:file, :operator, :triage)))
+          # Explicit keywords, and list takes no catch-all (#1267): a new
+          # parser option that never reaches the browser raises here instead
+          # of being swallowed. --ranked is the documented compat no-op.
+          @out.puts(browser.list(file: options[:file], operator: options[:operator], triage: options[:triage]))
         end
         EXIT_OK
       end
@@ -106,7 +109,7 @@ module Saboteur
       # One ordering everywhere (#1150): the terminal report's ranked order
       # is the default, exactly as the findings carry it; --ranked stays
       # accepted for compatibility.
-      def list(file: nil, operator: nil, triage: nil, **)
+      def list(file: nil, operator: nil, triage: nil)
         survivors = ranked_order(filtered(file, operator, triage))
         return "no survivors#{filters_note(file, operator, triage)}" if survivors.empty?
 
@@ -135,7 +138,7 @@ module Saboteur
       def detail_lines(survivor, finding)
         [
           "#{survivor[:path]}:#{survivor[:line]}  #{survivor[:operator]}  #{survivor[:digest]}",
-          *classification_line(survivor[:classification]),
+          *classification_line(survivor[:classification], survivor[:gap_kind]),
           "",
           "- #{finding['original'] || original_line(survivor)}",
           "+ #{finding['replacement'] || survivor[:replacement]}",
@@ -146,10 +149,10 @@ module Saboteur
       end
 
       # The same wording the terminal survivor block uses (#1183).
-      def classification_line(label)
+      def classification_line(label, kind = nil)
         return [] unless label
 
-        reason = Reporter::SurvivorHints.label_reason(label)
+        reason = Reporter::SurvivorHints.label_reason(label, kind: kind)
         ["classification: #{label}#{" - #{reason}" if reason}"]
       end
 
@@ -238,7 +241,8 @@ module Saboteur
             entry.fetch("mutants", []).select { |m| m["status"] == "Survived" }.map do |m|
               { path: path, line: m.dig("location", "start", "line").to_i, operator: m["mutatorName"],
                 digest: m["id"], replacement: m["replacement"], classification: m["classification"],
-                subject: m["subject"], covered: m["coveredBy"] || [], source: entry["source"] }
+                gap_kind: m["gapKind"], subject: m["subject"], covered: m["coveredBy"] || [],
+                source: entry["source"] }
             end
           end
           survivors

data/lib/saboteur/cli/whole_suite_map_lookup.rb

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The whole-suite coverage map a finished run hands to survivor
+    # presentation, and the notice for a scoped run that has none.
+    module WholeSuiteMapLookup
+      private
+
+      # No engine or no cache: no whole-suite map can exist, so the survivor
+      # block keeps its legacy covered-by line over an impossible build (review C1).
+      def whole_suite_map_for(engine, report)
+        warn_survivors_unconfirmed(report, engine)
+        return engine.whole_suite_coverage_map if engine&.whole_suite_map_lookup?
+
+        Reporter::SurvivorList::NO_WHOLE_SUITE_LOOKUP
+      end
+
+      # A scoped run's survivors may be pinned by a spec it never loaded.
+      # With no whole-suite map to check, say so once, even under --quiet
+      # (#1286). Verdicts, score and exit code are unchanged.
+      def warn_survivors_unconfirmed(report, engine)
+        return if report.unignored_survivors.empty?
+        return unless engine&.whole_suite_map_lookup? && engine.scoped_selection?
+        return if engine.whole_suite_coverage_map
+
+        @err.puts "saboteur: survivors unconfirmed: no whole-suite coverage map; " \
+                  "run `saboteur run --all` to build one"
+      end
+    end
+  end
+end

data/lib/saboteur/cli.rb

@@ -13,7 +13,9 @@ require_relative "cli/error_cause"
 require_relative "cli/exit_status"
 require_relative "cli/baseline_gate"
 require_relative "preview"
+require_relative "cli/color_option"
 require_relative "cli/run_reporting"
+require_relative "cli/whole_suite_map_lookup"
 require_relative "cli/survivors_command"
 require_relative "cli/explain_command"
 require_relative "cli/source_set"
@@ -43,7 +45,9 @@ module Saboteur
     include Baseline::Command
     include ExitStatus
     include BaselineGate
+    include ColorOption
     include RunReporting
+    include WholeSuiteMapLookup
     include SurvivorsCommand
     include ExplainCommand
     include SourceSet
@@ -100,7 +104,7 @@ module Saboteur
     end
 
     def call
-      command = @argv.shift
+      command = @command = @argv.shift
       case command
       when "run" then run_command
       when "baseline" then baseline
@@ -109,7 +113,7 @@ module Saboteur
       when "doctor" then doctor_command
       when "badge", "trend" then history_entry(command)
       when "version", "--version" then @out.puts(VERSION) || EXIT_OK
-      when "help", "--help", "-h" then show_help(@argv.shift)
+      when "help", "--help", "-h" then help_command
       when "agent-skill" then @out.print(AgentSkill::TEXT) || EXIT_OK
       else preset_or_usage_error(command)
       end