saboteur 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e6b6d8e50fff66a62fceb86427129fb8223251089a56a538265cc2ca0437559
-  data.tar.gz: 5ccca5b91560563ef6b6c2da93dc9191498074b714793e8586cbfa57dfbecf66
+  metadata.gz: 0a4dcacd09e6b4ca97537446ae6cbc73b13fb2c6dabcc26f22ea26784e869151
+  data.tar.gz: 83c7e9f8121a1193c518cbfcba50b825d13b0e08ccd90f3085f88d932855fd03
 SHA512:
-  metadata.gz: 1adf971a3548189acb63ee19e382d98f91cc9c3b9980bdc9d92e903754ab96d1aebb706c95cc8b7da4ee3a4eb851311b94b35f3f599213aa7e1e787adceff282
-  data.tar.gz: b11f8aba3ffa20e5f97d68ef2422eca609c6277e0d8dc408d30a70851342d1f64c97a563224a26a6f0d1652321e200242230bc85e5e62cd02428b7a8e21e24b5
+  metadata.gz: a9baa6f9af8e3f2ecd0e2fd661104550e23b7b5e2f368d4cd996b5648994537888d88ba1130477525b93d4df13a756585eed3f9ffb27f309057e7452d069a982
+  data.tar.gz: 782690794b535288178addb949cf7b0e530e19d4e55acd20c837903f4ddb8818581b42cacfc5af1d1ccb7ba4a6dd9e0cbd84a5059f143407f99195e2ed14a046

data/CHANGELOG.md

@@ -6,6 +6,121 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [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
@@ -247,6 +265,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/lib/saboteur/attribute_finder.rb

@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+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?
+
+      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/cli/presets.rb

@@ -14,6 +14,10 @@ module Saboteur
                       --html .saboteur/audit-report.html]
       }.freeze
 
+      # 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
+
       private
 
       def preset_or_usage_error(command)
@@ -31,10 +35,46 @@ module Saboteur
         # 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)")
+        @err.puts("saboteur: preset '#{name}': #{preset_banner(flags).join(' ')} (explicit flags override)")
         @argv = flags + @argv
         run_command
       end
+
+      # The banner is the reader's only record of the effective settings,
+      # so a preset flag the user also passed shows the user's spelling -
+      # the later occurrence wins (#666). Flags the user did not override
+      # print as the preset declares them.
+      def preset_banner(flags)
+        overrides = user_flag_overrides
+        banner = []
+        index = 0
+        while index < flags.size
+          if VALUE_FLAGS.include?(flags[index])
+            banner.concat(overrides.fetch(flags[index], [flags[index], flags[index + 1]]))
+            index += 2
+          else
+            banner << flags[index]
+            index += 1
+          end
+        end
+        banner
+      end
+
+      # Each long flag the user passed, mapped to its effective spelling:
+      # the last occurrence, verbatim, with its separate value token when
+      # the flag takes one.
+      def user_flag_overrides
+        overrides = {}
+        @argv.each_with_index do |arg, index|
+          name = arg[/\A--[^=]+/] or next
+          if arg.include?("=")
+            overrides[name] = [arg]
+          elsif VALUE_FLAGS.include?(name) && @argv[index + 1]
+            overrides[name] = [name, @argv[index + 1]]
+          end
+        end
+        overrides
+      end
     end
   end
 end

data/lib/saboteur/cli/run_budget_options.rb

@@ -14,7 +14,9 @@ module Saboteur
           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|
+        opts.on("--max-duration DURATION", "Wall-clock budget for the whole run, e.g. 10m; exit 4 when spent - " \
+                                           "the clock starts at engine entry, so boot, baselines and the " \
+                                           "coverage map spend it too") 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|

data/lib/saboteur/cli/source_set.rb

@@ -18,24 +18,6 @@ module Saboteur
         raise UsageError, empty_source_set_message
       end
 
-      # A --since ref whose resolved range diffs empty yields 0 subjects
-      # and a green run over nothing: `saboteur pr <merge_sha>` on a
-      # checkout AT the merge diffs the merge against itself (#643).
-      # Refuse like a typo'd ref: exit 2, name the base and the range.
-      def refuse_empty_since_range
-        ref = config["since"]
-        return unless ref
-
-        paths = Selection::GitDiff.changed_paths(ref, root: config.root)
-        return unless paths.values.all?(&:empty?)
-
-        base = Selection::GitDiff.merge_base(ref, root: config.root)
-        raise UsageError, "--since #{ref}: the resolved range #{base}..the working tree has no changes - " \
-                          "the run would pass with 0 subjects. A checkout AT the ref (the CI merge-sha " \
-                          "checkout) diffs it against itself: fetch the merge's parent, or point --since " \
-                          "at the base of the change under test"
-      end
-
       def empty_source_set_message
         include_patterns = config["include"]
         matched = include_patterns.flat_map { |pattern| Dir.glob(pattern, base: config.root) }

data/lib/saboteur/cli.rb

@@ -155,7 +155,6 @@ module Saboteur
       return preview if options[:list_operators] || options[:dry_run]
 
       refuse_empty_source_set
-      refuse_empty_since_range
       execute_run
     rescue ConfigError => e
       @err.puts("saboteur: #{e.message}")
@@ -393,7 +392,10 @@ module Saboteur
       opts.on("--format FORMAT", %w[text agent json], "text, agent or json (--dry-run inventory)") { |v| @format = v }
       opts.on("--agent", "Same as --format agent") { @format = "agent" }
       opts.on("--verbose", "Text report: also print score split, timings and kill causes;",
-              "a crash prints its backtrace") { @verbose = true }
+              "a crash prints its backtrace") do
+        @verbose = true
+        set(:verbose, true)
+      end
       opts.on("--[no-]color", "Colour the text report (default: on for a terminal unless NO_COLOR is set)") do |v|
         @color = v ? :always : :never
       end

data/lib/saboteur/config.rb

@@ -86,7 +86,10 @@ module Saboteur
       "fingerprint_extra" => [],
       "threshold" => nil,
       "max_timeouts" => nil,
-      "max_errors" => nil
+      "max_errors" => nil,
+      # --verbose also lands here, so boot-time output filters (the rspec
+      # load-error report, #608) can keep their raw text behind the flag.
+      "verbose" => false
     }.freeze
 
     INTEGER_KEYS = %w[jobs max_memory_mb max_processes max_mutants_per_method seed baseline_passes].freeze

data/lib/saboteur/config_file.rb

@@ -9,29 +9,34 @@ module Saboteur
   # boots, so it cannot reference app constants - plain Ruby and ENV only.
   module ConfigFile
     # The assignment target. One setter per Config key; anything else is an
-    # unknown setting. Records the line of each assignment so validation
-    # errors can point at it.
+    # unknown setting.
     class Settings
       def initialize
         @values = {}
-        @lines = {}
       end
 
-      attr_reader :values, :lines
+      attr_reader :values
 
-      Config::DEFAULTS.each_key do |key|
+      (Config::DEFAULTS.keys - ["integration"]).each do |key|
         define_method("#{key}=") do |value|
           @values[key] = value
-          @lines[key] = caller_locations(1, 1).first.lineno
         end
       end
 
+      def integration=(value)
+        line = caller_locations(1, 1).fetch(0).lineno
+        unless value.is_a?(String)
+          raise ConfigError, "#{line}: integration must be a String, got #{value.inspect}; use \"rspec\""
+        end
+
+        @values["integration"] = value
+      end
+
       # Repeatable per-path score gates (#473), the one setting that takes
       # arguments: c.score_gate "app/payments/**/*", min_score: 95. Values
       # are validated later, on the effective Config.
       def score_gate(pattern, min_score:)
         (@values["score_gates"] ||= []) << { "pattern" => pattern, "min_score" => min_score }
-        @lines["score_gates"] = caller_locations(1, 1).first.lineno
       end
 
       Config::INTEGER_KEYS.each do |key|
@@ -41,7 +46,6 @@ module Saboteur
             raise ConfigError, "#{line}: #{key} must be an Integer, got #{value.inspect}"
           end
           @values[key] = value
-          @lines[key] = caller_locations(1, 1).first.lineno
         end
       end
     end

data/lib/saboteur/custom_map.rb

@@ -64,7 +64,14 @@ module Saboteur
       unless spec.is_a?(String)
         raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; spec paths must be Strings"
       end
-      return if key.is_a?(Regexp) && spec.match?(/\\\d/) # backreference filled in at match time
+
+      numbered = key.is_a?(Regexp) && spec.match?(/\\\d/)
+      named = key.is_a?(Regexp) && spec.match?(/%[-0-9]*[<{][^>}]+[>}]|\\k</)
+      if numbered && named
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; " \
+                           'regex map specs support \1 backreferences only'
+      end
+      return if numbered # backreference filled in at match time
 
       expanded = File.expand_path(spec, root)
       unless expanded.start_with?("#{root}/")
@@ -72,6 +79,10 @@ module Saboteur
       end
       return if Dir.glob(expanded).any?
 
+      if named
+        raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}; " \
+                           'regex map specs support \1 backreferences only'
+      end
       raise ConfigError, "#{path}: #{key.inspect} maps to #{spec.inspect}, which matches no file"
     end
 

data/lib/saboteur/dirty_tree_warning.rb

@@ -2,8 +2,9 @@
 # frozen_string_literal: true
 
 module Saboteur
-  # The warning shown before a run on a tree with uncommitted changes
-  # (#309, #316). Mutants run your code and can change the tree, so the
+  # The warning shown before a run on a tree with uncommitted
+  # changes (#309, #316); the headline says uncommitted or untracked, so a
+  # tree of only scratch files is not read as edits (#604). Mutants run your code and can change the tree, so the
   # warning stays; it splits the raw count so a tree full of notes or trial
   # setup files does not read like application edits about to be mutated.
   #
@@ -101,7 +102,8 @@ module Saboteur
       groups = [scope.empty? ? "none inside the mutation scope" : counted("inside the mutation scope", scope),
                 counted("outside it", outside)]
       groups << counted("saboteur setup file(s)", setup) unless setup.empty?
-      "saboteur: warning: #{@state.changed_files} uncommitted change(s) in the working tree: #{groups.join(', ')}."
+      "saboteur: warning: #{@state.changed_files} uncommitted or untracked change(s) in the working tree: " \
+        "#{groups.join(', ')}."
     end
 
     def counted(label, changes)

data/lib/saboteur/doctor.rb

@@ -102,8 +102,12 @@ module Saboteur
           @out.puts %(Seatbelt (opt-in, #436): probe #{Execution::Seatbelt.probe} - capability probe only, ) \
                     "not verified isolation"
         elsif RUBY_PLATFORM.match?(/darwin/i)
+          # Point at the way OUT of the degraded state, like the run
+          # warning does (#667): the opt-in Seatbelt sandbox, or silence.
           @out.puts "macOS: mutants run unsandboxed (Landlock is Linux-only) - a container contains " \
                     "filesystem writes outside the project"
+          @out.puts %(macOS: opt into the sandbox with c.sandbox = "seatbelt" ) \
+                    "(docs/guides/macos-seatbelt-sandbox.md), or set c.sandbox = false to silence this"
           @out.puts "Network: never restricted on any platform, and a plain container keeps outbound " \
                     "access - deny or stub the network when a mutant could reach real APIs"
         end