saboteur 0.8.0 → 0.9.0

data/lib/saboteur/engine/partial_invalidation.rb

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Which spec files a partial coverage rebuild would have to rerun, or
+    # :full when the whole map must be rebuilt (#46, step 2). Pure: it reads
+    # two inputs snapshots and a coverage map and touches nothing else.
+    #
+    # An allowlist, not a blocklist. Coverage never records a test reading a
+    # fixture, a YAML file, an ENV value or a template, so no changed file
+    # can be proven harmless by absence. Only two kinds of change may take
+    # the partial path: a spec file of the suite, and an included source
+    # file with recorded coverage evidence that did not run while the app
+    # loaded. Every other change, and every added or removed file, is :full,
+    # as is a change of root, settings, runtime or snapshot format.
+    #
+    # The stale files come back in the order the map's full run used, so a
+    # rerun keeps the relative order that run had.
+    class PartialInvalidation
+      FULL = :full
+      # Placeholder, to be fitted from measurements; not configuration.
+      THRESHOLD = 0.5
+      SAME = %w[format root runtime settings].freeze
+
+      # included: relative paths of the included source files.
+      # spec_files: relative paths of the suite's spec files.
+      # status_file: whether RSpec picks examples from its generated status
+      # file (--only-failures, --next-failure), which no snapshot covers.
+      # RSpec ids name their file: "./spec/a_spec.rb[1:2]" is spec/a_spec.rb.
+      def self.spec_of(id)
+        id.split("[").first.delete_prefix("./")
+      end
+
+      def initialize(map:, root:, included:, spec_files:, status_file: false)
+        @status_file = status_file
+        @map = map
+        @root = Selection::CoverageMap.canonical(root)
+        @included = included
+        @spec_files = spec_files
+      end
+
+      def stale_specs(base, current)
+        return FULL if @status_file
+        return FULL unless SAME.all? { |key| base[key] == current[key] }
+
+        changed = changed_files([base, current].map { |snapshot| snapshot["files"] })
+        return FULL unless changed
+
+        stale = changed.each_with_object([]) do |file, specs|
+          found = specs_for(file)
+          return FULL unless found
+
+          specs.concat(found)
+        end
+        ordered(stale.uniq).then { |specs| heavy?(specs) ? FULL : specs }
+      end
+
+      # The part of the recorded spec time these files hold, 0 when none was recorded.
+      def share(specs)
+        total = weights.values.sum
+        total.zero? ? 0.0 : specs.sum { |file| weights.fetch(file, 0) }.fdiv(total)
+      end
+
+      private
+
+      # nil when a file was added, removed or unreadable on either side.
+      def changed_files(snapshots)
+        before, after = snapshots
+        return nil unless before.keys.sort == after.keys.sort
+        return nil if (before.values + after.values).include?(false)
+
+        before.keys.reject { |file| before[file] == after[file] }
+      end
+
+      def specs_for(file)
+        return [file] if @spec_files.include?(file)
+        return nil unless @included.include?(file) && evidence?(File.join(@root, file))
+
+        touching(File.join(@root, file)).then { |specs| specs if specs.all? { |spec| @spec_files.include?(spec) } }
+      end
+
+      def evidence?(path)
+        [@map.lines, @map.methods].any? { |hits| (hits[path] || {}).values.any?(&:any?) } &&
+          [@map.load_lines, @map.load_methods].none? { |hits| hits[path]&.any? } &&
+          !@map.preloaded?(path)
+      end
+
+      def touching(path)
+        ids = [@map.lines, @map.methods].flat_map { |hits| (hits[path] || {}).values.flatten }
+        ids.map { |id| spec_of(id) }.uniq
+      end
+
+      def spec_of(id)
+        self.class.spec_of(id)
+      end
+
+      def ordered(stale)
+        run_order = @map.tests.map { |id| spec_of(id) }.uniq
+        run_order.select { |file| stale.include?(file) } + (stale - run_order).sort
+      end
+
+      # Stale share of the recorded time, by spec file, never above THRESHOLD.
+      def heavy?(specs)
+        total = weights.values.sum
+        total.zero? || share(specs) > THRESHOLD
+      end
+
+      def weights
+        @map.tests.group_by { |id| spec_of(id) }
+            .transform_values { |ids| ids.sum { |id| @map.durations.fetch(id, 0) } }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/partial_merge.rb

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # The map a partial rebuild produces (#46, step 3): the base map with all
+    # evidence of the rerun spec files removed, plus the fresh map the child
+    # recorded over just those files. Whole spec files are replaced, never
+    # single examples, since a file's example ids can shift when it changes.
+    # Load-time evidence, loaded files and preloaded files carry over from
+    # both: every run boots the same app.
+    module PartialMerge
+      module_function
+
+      def call(base, fresh, spec_files)
+        specs = spec_files.to_set
+        dropped = base.tests.select { |id| specs.include?(PartialInvalidation.spec_of(id)) }.to_set
+        trimmed = Selection::CoverageMap.new(
+          lines: without(base.lines, dropped), methods: without(base.methods, dropped),
+          branches: without(base.branches, dropped), tests: base.tests.reject { |id| dropped.include?(id) },
+          durations: base.durations.except(*dropped),
+          load_lines: base.load_lines, load_methods: base.load_methods,
+          loaded_files: base.loaded_files, preloaded: base.preloaded.to_a, build_seconds: base.build_seconds
+        )
+        Selection::CoverageMap.combine([trimmed, fresh])
+      end
+
+      # {file => {line-or-span => ids}} without the dropped ids. An entry left
+      # with no test is removed, and so is a file left with no entry: a file
+      # with no test behind it must read as no evidence, not as covered.
+      def without(hits, dropped)
+        hits.each_with_object({}) do |(file, by_line), acc|
+          kept = by_line.transform_values { |ids| ids.reject { |id| dropped.include?(id) } }
+          kept.reject! { |_, ids| ids.empty? }
+          acc[file] = kept unless kept.empty?
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/engine/pipelines.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../execution/test_command_shape"
+
 module Saboteur
   class Engine
     # The two run pipelines: in-process (boot, coverage, workers) and the
@@ -22,7 +24,7 @@ module Saboteur
                       mutate(subjects, files, integration, scope, ignore_list,
                              load_lines:, load_methods:)
                     end
-          @diagnostics.warnings.concat(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
+          @diagnostics.add_warnings(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
           build_report(results, subjects, scope, started)
         ensure
           # Cleanup runs however the call ends - a partway boot failure, no
@@ -43,10 +45,16 @@ module Saboteur
       def call_external(ignore_list, started)
         @diagnostics.inform("external test command: #{config['test_command']} " \
                             "(serial, no coverage, unsandboxed, mutants applied in a disposable copy)")
+        if Execution::TestCommandShape.multi_file_ruby?(config["test_command"])
+          @diagnostics.warn("use the framework's multi-file form (bin/rails test f1 f2, rspec f1 f2) or a " \
+                            "shell loop (for f in ...; do ruby \"$f\" || exit 1; done)\n  " \
+                            "the test command hands several test files to one ruby: ruby executes only " \
+                            "the first, so the rest never run and their mutants silently survive (#611)")
+        end
         files = config.included_files
         subjects, scope = select_subjects(files)
         results = subjects.empty? ? [] : mutate_external(subjects, scope, ignore_list)
-        @diagnostics.warnings.concat(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
+        @diagnostics.add_warnings(ignore_list.apply(results, unscoped_digests: @unscoped_digests))
         build_report(results, subjects, scope, started)
       end
 
@@ -78,7 +86,7 @@ module Saboteur
         end
         run_candidates(runnable_subjects, runnable_lists, scheduler, nil, ignore_list)
       ensure
-        runner.close
+        runner&.close
       end
 
       # Warn loudly when the command cannot see mutants at all: an

data/lib/saboteur/engine/reference_specs.rb

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # The specs that read a constant a source file defines, or require it: the
+    # cold-start choice for a file with no spec by name. The constant match is
+    # the lexical matching #538 uses for changed specs; the require match
+    # covers a file that defines only top-level methods. A file no spec reads or requires, or one read by more than
+    # CAP specs (a hub: the choice is not selective), gets no entry.
+    class ReferenceSpecs
+      CAP = 10
+      REQUIRE = /^\s*(require_relative|require)[ (]\s*["']([^"']+)["']/
+
+      # constants: file => the constants it defines, as TestGuess shapes them
+      # for ConstantReads.
+      def initialize(root, constants)
+        @root = root
+        @constants = constants
+      end
+
+      # chosen: file => sorted root-relative spec paths; crowded: file => how
+      # many specs read it, for the files over the cap (no choice was made).
+      Found = Data.define(:chosen, :crowded)
+
+      # The announcement for the files that got specs by reference.
+      def self.note(referenced)
+        named = referenced.map { |file, specs| "#{file} (#{specs.join(', ')})" }
+        "inferred specs: selected by constant reference or require, not by name: #{named.join(', ')}; " \
+          "a spec that reaches the file another way is not found"
+      end
+
+      def self.crowd_note(count) = "#{count} specs reference or require it, over the cap of #{CAP}"
+
+      # files: root-relative source files; spec_paths: root-relative spec
+      # files of the suite.
+      def call(files, spec_paths)
+        absolute = spec_paths.map { |path| File.join(@root, path) }
+        absolute.select! { |path| File.file?(path) && !File.symlink?(path) }
+        found = files.to_h { |file| [file, readers_of(file, absolute)] }.reject { |_, readers| readers.empty? }
+        crowded, chosen = found.partition { |_, readers| readers.size > CAP }.map(&:to_h)
+        Found.new(chosen: chosen, crowded: crowded.transform_values(&:size))
+      end
+
+      private
+
+      def readers_of(file, absolute_specs)
+        read = @constants.call(file).flat_map { |constant| ConstantReads.across(absolute_specs, constant).keys }
+        (read + requirers_of(file, absolute_specs)).uniq.sort.map { |path| path.delete_prefix("#{@root}/") }
+      end
+
+      # Specs that require the file: by path from the spec (require_relative)
+      # or by load path from the file's source root (require "a/b" for
+      # lib/a/b.rb). A bare basename is not a load path, so it matches nothing.
+      def requirers_of(file, absolute_specs)
+        stem = File.join(@root, file).delete_suffix(".rb")
+        loadable = file.delete_suffix(".rb").sub(%r{\A[^/]+/}, "")
+        absolute_specs.select { |spec| requires?(spec, stem, loadable) }
+      end
+
+      def requires?(spec, stem, loadable)
+        File.read(spec, encoding: "UTF-8").scrub.scan(REQUIRE).any? do |kind, target|
+          target = target.delete_suffix(".rb")
+          kind == "require_relative" ? File.expand_path(target, File.dirname(spec)) == stem : target == loadable
+        end
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/saboteur/engine/result_cache.rb

@@ -4,6 +4,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require "securerandom"
 require_relative "../text"
 
 module Saboteur
@@ -25,6 +26,7 @@ module Saboteur
     # stale.
     class ResultCache
       FORMAT = 1
+      MAX_BYTES = 64 * 1024 * 1024
       STORED = %i[killed survived timeout].freeze
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
       # Dependency declarations themselves, so the no-lockfile library
@@ -34,9 +36,15 @@ module Saboteur
 
       SOURCE_EXCLUDES = %w[.git vendor node_modules].freeze
 
+      # Seconds between checkpoint saves while verdicts arrive, so a run
+      # killed mid-phase (OOM, CI timeout, SIGKILL) keeps what it finished
+      # (#471).
+      SAVE_INTERVAL = 30
+
       # suite_digest: SuiteFiles#digest, so an edit to a spec helper or
       # support file invalidates every verdict.
-      def initialize(path:, root:, inputs:, suite_digest: "", coverage: nil, fallback_files: [])
+      def initialize(path:, root:, inputs:, suite_digest: "", coverage: nil, fallback_files: [],
+                     save_interval: SAVE_INTERVAL, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
         @path = path
         @root = root
         @inputs = inputs
@@ -47,6 +55,9 @@ module Saboteur
         @fallback_files = fallback_files.map { |file| File.expand_path(file, root) }.sort
         @entries = load
         @file_digests = {}
+        @save_interval = save_interval
+        @clock = clock
+        @last_saved = clock.call
       end
 
       # The stored verdict as a hash (status, reason, killed_by, kill_cause,
@@ -67,15 +78,39 @@ module Saboteur
           "reason" => result.reason, "killed_by" => result.killed_by, "kill_cause" => result.kill_cause,
           "runtime" => result.runtime
         }
+        checkpoint if @clock.call - @last_saved >= @save_interval
       end
 
+      # Written to a temp file and renamed, so a kill mid-write leaves the
+      # previous complete file, never a truncated one. A failed write or
+      # rename removes the temp file and raises.
       def save
         FileUtils.mkdir_p(File.dirname(@path))
-        File.write(@path, JSON.generate(format: FORMAT, entries: @entries))
+        temp = "#{@path}.#{SecureRandom.hex(8)}.tmp"
+        begin
+          # "wx": a planted file or symlink at the temp name is never followed.
+          File.open(temp, "wx", 0o600) { |out| out.write(JSON.generate(format: FORMAT, entries: @entries)) }
+          File.rename(temp, @path)
+        rescue StandardError
+          FileUtils.rm_f(temp)
+          raise
+        end
+        @last_saved = @clock.call
       end
 
       private
 
+      # A mid-run save is a safety net, so it is best effort: a full disk or
+      # an unwritable directory must not abort a run that is still producing
+      # verdicts. The wait restarts either way, so a broken disk is tried
+      # once per interval, not once per verdict. The final save is not
+      # swallowed (Engine calls #save).
+      def checkpoint
+        save
+      rescue SystemCallError
+        @last_saved = @clock.call
+      end
+
       # The current project source files, relative and sorted. A file added
       # after the map was built changes the set and invalidates every stored
       # verdict, whether or not any watched file references it yet.
@@ -86,13 +121,41 @@ module Saboteur
                            .join("\0")
       end
 
+      # The file is untrusted input (a restored cache, a --resume directory):
+      # read only as a regular file, never a symlink or FIFO, under a size
+      # cap, and kept only when entries is a Hash of Hashes.
       def load
-        data = JSON.parse(Text.utf8_strict(File.read(@path)))
-        data["format"] == FORMAT ? data["entries"] : {}
-      rescue SystemCallError, JSON::ParserError
+        return {} unless File.lstat(@path).file?
+
+        text = slurp
+        return {} unless text
+
+        data = JSON.parse(Text.utf8_strict(text))
+        entries = data["entries"] if data.is_a?(Hash) && data["format"] == FORMAT
+        well_formed?(entries) ? entries : {}
+      rescue SystemCallError, JSON::ParserError, ArgumentError, EncodingError
         {}
       end
 
+      def slurp
+        File.open(@path, File::RDONLY | File::NONBLOCK | File::NOFOLLOW) do |io|
+          text = io.read(MAX_BYTES)
+          text if io.eof?
+        end
+      end
+
+      def well_formed?(entries)
+        entries.is_a?(Hash) && entries.values.all? { |entry| entry.is_a?(Hash) && typed?(entry) }
+      end
+
+      # The fields the reports read, typed so a crafted entry cannot crash
+      # them.
+      def typed?(entry)
+        STORED.map(&:to_s).include?(entry["status"]) && (entry["runtime"].nil? || entry["runtime"].is_a?(Numeric)) &&
+          %w[reason kill_cause].all? { |key| entry[key].nil? || entry[key].is_a?(String) } &&
+          entry["killed_by"].is_a?(Array) && entry["killed_by"].all?(String)
+      end
+
       def key(subject, mutation)
         "#{subject.id} #{mutation.digest(subject_start: subject.start_byte, original_source: subject.file_source)}"
       end

data/lib/saboteur/engine/resume_manifest.rb

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+
+module Saboteur
+  class Engine
+    # Identity file for a --resume directory (#471). The verdicts live in
+    # ResultCache; this only records what the run was computed from, so a
+    # later run with other inputs fails loudly instead of reusing the
+    # directory under a different meaning.
+    #
+    # The file is untrusted input: it is read only when it is a regular
+    # file (never a FIFO or a symlink), under a size cap, and must hold
+    # exactly the three expected keys with bounded String values.
+    class ResumeManifest
+      FORMAT = 1
+      FILE = "manifest.json"
+      KEYS = %w[format identity version].freeze
+      MAX_BYTES = 4096
+      MAX_FIELD = 512
+
+      # Raised when the directory belongs to another run or cannot be read.
+      class Mismatch < StandardError; end
+
+      # identity: a String that changes whenever the run's inputs change
+      # (the RunFingerprint digest joined with the settings that pick the
+      # mutants), at most MAX_FIELD characters.
+      def initialize(directory:, identity:)
+        @directory = directory
+        @identity = identity
+      end
+
+      def path
+        File.join(@directory, FILE)
+      end
+
+      # Creates the manifest in a fresh directory, accepts a matching one,
+      # and raises Mismatch for anything else.
+      def verify!
+        File.lstat(path)
+        compare(read)
+      rescue Errno::ENOENT
+        write
+      end
+
+      private
+
+      def compare(stored)
+        return if stored["identity"] == @identity && stored["version"] == VERSION
+
+        raise Mismatch, "#{path}: the run inputs changed since this directory was created; " \
+                        "delete it or choose a new --resume path"
+      end
+
+      def read
+        raise Mismatch, "#{path}: unreadable manifest" unless File.lstat(path).file?
+
+        validate(parse(slurp))
+      rescue SystemCallError
+        raise Mismatch, "#{path}: unreadable manifest"
+      end
+
+      def slurp
+        File.open(path, File::RDONLY | File::NONBLOCK | File::NOFOLLOW) do |io|
+          text = io.read(MAX_BYTES) || +""
+          raise Mismatch, "#{path}: manifest too large" unless io.eof?
+
+          text
+        end
+      end
+
+      def parse(text)
+        raise Mismatch, "#{path}: unreadable manifest" unless text.force_encoding(Encoding::UTF_8).valid_encoding?
+
+        JSON.parse(text)
+      rescue JSON::ParserError
+        raise Mismatch, "#{path}: unreadable manifest"
+      end
+
+      def validate(data)
+        raise Mismatch, "#{path}: unsupported manifest format" unless
+          data.is_a?(Hash) && data.keys.sort == KEYS && data["format"] == FORMAT && bounded?(data)
+
+        data
+      end
+
+      def bounded?(data)
+        %w[identity version].all? { |key| data[key].is_a?(String) && data[key].length <= MAX_FIELD }
+      end
+
+      # Written to a private temp file and linked into place: link fails
+      # when another run created the manifest first, and then that run's
+      # manifest is the one compared.
+      def write
+        FileUtils.mkdir_p(@directory)
+        temp = "#{path}.#{Process.pid}.#{SecureRandom.hex(4)}.tmp"
+        File.write(temp, JSON.generate(format: FORMAT, version: VERSION, identity: @identity))
+        File.link(temp, path)
+        nil
+      rescue Errno::EEXIST
+        compare(read)
+      ensure
+        FileUtils.rm_f(temp) if temp
+      end
+    end
+  end
+end

data/lib/saboteur/engine/run_budget.rb

@@ -35,8 +35,11 @@ module Saboteur
 
       # Absolute monotonic deadline shared with the schedulers (forked
       # workers inherit it): a subject's remaining mutants stop once it
-      # passes, so the overshoot after a spent budget stays under one
-      # mutant deadline.
+      # passes. New mutation work never overshoots more than the fork in
+      # flight; a subject the deadline cut mid-list still confirms the
+      # kills it already measured (#588), and those checks and retries
+      # fork uncapped - the overshoot is bounded by the subject's
+      # distinct killing sequences times their full timeout.
       def budget_deadline
         config["max_duration"] && (@run_started + config["max_duration"])
       end
@@ -61,11 +64,11 @@ module Saboteur
 
         needed = per_pass - remaining
         raise BudgetPhaseTimeout,
-              "the --max-duration budget cannot cover the coverage map build: baseline passes took about " \
-              "#{per_pass.round}s each, only #{remaining.round(1)}s remain, and a cold build needs about one " \
-              "more full pass and keeps nothing when it is cut off. Re-run with --max-duration about " \
-              "#{needed.round}s higher, fewer --baseline-passes, or once without --max-duration so the " \
-              "coverage cache is built for later --incremental runs"
+              "re-run with --max-duration about #{needed.round}s higher, fewer --baseline-passes, or once " \
+              "without --max-duration so the coverage cache is built for later --incremental runs: " \
+              "the budget cannot cover the coverage map build - baseline passes took about " \
+              "#{per_pass.round}s each, only #{remaining.round(1)}s remain, and a cold build needs about " \
+              "one more full pass and keeps nothing when it is cut off"
       end
 
       # Boot and baselines can spend the budget by themselves: stop before

data/lib/saboteur/engine/run_fingerprint.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "json"
+require_relative "../config"
 require_relative "../text"
 require_relative "data_inputs"
 
@@ -13,7 +14,7 @@ module Saboteur
     class RunFingerprint
       FORMAT_VERSION = 1
       MANIFESTS = %w[Gemfile gems.rb Gemfile.lock gems.locked .rspec .rspec-local].freeze
-      LOCATION_SETTINGS = %w[cache_dir json_report html_report score_history].freeze
+      LOCATION_SETTINGS = Config::OUTPUT_KEYS
       ENTRY_KINDS = %w[ruby manifest boot hook source_plugin extra data].freeze
       EXCLUDED_DIRECTORIES = %w[.git vendor node_modules].freeze
       Entry = Data.define(:path, :kind, :state, :sha256, :required)

data/lib/saboteur/engine/sandbox_policy.rb

@@ -39,8 +39,7 @@ module Saboteur
         # same line twice (D's review, #178).
         unless @sandbox_note_given
           @sandbox_note_given = true
-          @diagnostics.warn("sandbox is on but #{self.class.sandbox_gap(abi)}; children run with the hazard guard " \
-                            "and canary only")
+          @diagnostics.warn(degraded_note(abi))
         end
         nil
       end
@@ -55,11 +54,30 @@ module Saboteur
       end
 
       def self.sandbox_gap(abi)
-        return "this kernel lacks Landlock (needs Linux 6.2+)" if abi.zero?
+        if abi.zero?
+          # Landlock is Linux-only: on macOS there is no kernel to upgrade,
+          # so name the platform instead of a Linux version (#667).
+          return "macOS has no Landlock" if Execution::Seatbelt.darwin?
+
+          return "this kernel lacks Landlock (needs Linux 6.2+)"
+        end
 
         "this kernel's Landlock ABI is #{abi} but ABI 3 (Linux 6.2+) is needed to restrict truncate()"
       end
 
+      # The degraded-run note: on macOS the gap is permanent, so point at
+      # the Seatbelt opt-in; on Linux the kernel wording stands alone
+      # (#667). Severity stays a warning - degrading confinement is never
+      # routine.
+      def degraded_note(abi)
+        gap = self.class.sandbox_gap(abi)
+        tail = "children run with the hazard guard and canary only"
+        return "sandbox is on but #{gap}; #{tail}" unless Execution::Seatbelt.darwin?
+
+        "sandbox is on but #{gap}; #{tail} - opt into the macOS sandbox with c.sandbox = \"seatbelt\" " \
+          "(docs/guides/macos-seatbelt-sandbox.md), or set c.sandbox = false to silence this"
+      end
+
       def restrict_hook
         writable = sandbox_writable_dirs
         ->(keep_fds) { Execution::Sandbox.restrict!(writable: writable, keep_fds: keep_fds) }
@@ -126,7 +144,8 @@ module Saboteur
       def check_sandbox_write_set(all_dirs, user_dirs)
         holder = all_dirs.find { |dir| path_contains?(dir, @root) }
         if holder
-          message = "sandbox grant #{holder} contains the project root; mutant children can write the whole tree"
+          message = "narrow the sandbox grant #{holder} so it no longer contains the project root\n  " \
+                    "sandbox grant #{holder} contains the project root; mutant children can write the whole tree"
           raise Error, %(#{message} - refusing under c.sandbox = "strict") if @config["sandbox"] == "strict"
 
           @diagnostics.warn(message)
@@ -135,7 +154,9 @@ module Saboteur
           (all_dirs - [dir]).each do |other|
             next unless path_contains?(dir, other)
 
-            @diagnostics.warn("sandbox grant #{dir} contains the granted dir #{other}; " \
+            safe_other = Text.display_safe(other)
+            @diagnostics.warn("drop the redundant sandbox grant #{safe_other}\n  " \
+                              "sandbox grant #{Text.display_safe(dir)} contains the granted dir #{safe_other}; " \
                               "the narrower grant is redundant")
           end
         end