saboteur 0.7.0 → 0.8.0

data/lib/saboteur/constant_subject.rb

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "subject"
+
+module Saboteur
+  # A constant assigned a hash or array literal, as a mutation subject
+  # (issue #306): `RULES = { ... }` or `TAGS = [ ... ]`, with an optional
+  # trailing `.freeze`. Only --since selection creates these (see
+  # Engine::SubjectSelection), and the diff scope narrows their mutants to
+  # the entries the diff changed.
+  #
+  # A constant is not a method, so the surgical def re-evaluation does not
+  # apply: mutants run by re-evaluating the whole file with the mutated
+  # assignment spliced in (Execution::Reevaluator#eval_whole_file, which
+  # silences the "already initialized constant" warning). Re-evaluation
+  # replaces the constant's object; code that reads the constant at test
+  # time sees the mutant, while anything that copied the old object at load
+  # time keeps it. consumer_lines names the reads a test can cover; the
+  # coverage map turns them into the mutant's tests.
+  class ConstantSubject < Subject
+    attr_reader :literal_node
+    # { "/abs/file.rb" => [lines reading the constant] } across the include
+    # set, filled in after selection (the finder sees one file at a time).
+    attr_accessor :consumer_lines
+    # { "/abs/file.rb" => [def start lines] }: the def each runtime read
+    # sits in, for the method-call counter fallback (endless defs have no
+    # line coverage).
+    attr_accessor :consumer_defs
+
+    def initialize(name:, owner:, file:, node:, literal_node:, file_source:, nesting:, frozen_literals:,
+                   consumer_lines: {}, consumer_defs: {})
+      super(name:, owner:, singleton: false, sclass: false, file:, node:, file_source:, nesting:,
+            frozen_literals:, sig_span: nil)
+      @literal_node = literal_node
+      @consumer_lines = consumer_lines
+      @consumer_defs = consumer_defs
+    end
+
+    # "Shop::RULES", or "RULES" at the top level. The :: separator keeps a
+    # constant's id apart from the Klass#method and Klass.method spellings.
+    def id
+      owner ? "#{owner}::#{name}" : name.to_s
+    end
+
+    # There is no method body to redefine: constants always take the
+    # whole-file evaluation path.
+    def whole_file_only?
+      true
+    end
+
+    # The assignment runs while the file loads, so its lines carry the load
+    # evidence; the reads of the constant in this file are the lines tests
+    # can cover.
+    def coverage_lines
+      ((start_line..end_line).to_a + Array(consumer_lines[file])).uniq
+    end
+
+    # Every edit sits inside the literal and is observable wherever the
+    # constant is read, so the assignment's own lines are the evidence that
+    # the edit ran (they execute at load, never inside a test).
+    def coverage_lines_for(_edit)
+      (start_line..end_line).to_a
+    end
+
+    def recovers?
+      false
+    end
+  end
+end

data/lib/saboteur/constant_subject_finder.rb

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "subject"
+require_relative "constant_subject"
+
+module Saboteur
+  # Finds constant assignments of hash and array literals - `RULES = { ... }`,
+  # `TAGS = [ ... ]`, with a trailing `.freeze` or a similar argument-free,
+  # block-free call - as mutation subjects for --since runs (issue #306).
+  #
+  # Unsupported forms are reported with a reason, never silently skipped: a
+  # namespaced target (`A::RULES = ...`), a conditional write
+  # (`RULES ||= ...`), and a non-literal value (a method call with
+  # arguments, another constant). Class factories (`Point = Data.define(...)`)
+  # are scopes, not data: they are reported neither way, and a constant
+  # inside the factory's block binds on the enclosing lexical scope, never
+  # on the class the factory builds (#352, mirroring SubjectFinder).
+  # Constants inside any other block are found but marked skipped, like
+  # SubjectFinder's defs, so the report names them.
+  class ConstantSubjectFinder
+    Parsed = Data.define(:subjects, :unsupported, :errors)
+
+    # A constant assignment saboteur cannot mutate, with the reason why.
+    Unsupported = Data.define(:name, :owner, :file, :node, :reason) do
+      def id
+        owner ? "#{owner}::#{name}" : name.to_s
+      end
+
+      def overlaps_lines?(lines)
+        first = node.location.start_line
+        last = node.location.end_line
+        if lines.is_a?(Range)
+          lines.begin <= last && first <= lines.end
+        else
+          lines.any? { |line| line.between?(first, last) }
+        end
+      end
+    end
+
+    CLASS_FACTORIES = SubjectFinder::CLASS_FACTORIES
+
+    # source: the text to parse when it is not the file on disk (the file as
+    # it was at an earlier commit).
+    def call(file, source: File.binread(file))
+      result = Prism.parse(source)
+      return Parsed.new(subjects: [], unsupported: [], errors: result.errors.map(&:message)) if result.failure?
+
+      ctx = { file: file, source: source, frozen: frozen_literals?(result) }
+      out = { subjects: [], unsupported: [], ambiguous: [] }
+      walk(result.value, [], out, **ctx)
+      reject_duplicates(out, **ctx)
+      demote_ambiguous(out, **ctx)
+      Parsed.new(subjects: out[:subjects], unsupported: out[:unsupported], errors: [])
+    end
+
+    private
+
+    # More than one write of the same constant in one file: re-evaluating
+    # the file runs them all, the later one always wins, and a mutant of
+    # any earlier literal is never observed. EVERY write counts - a guarded
+    # or non-literal second write (`RULES = {a: 1}; RULES = build_rules`)
+    # overwrites the first just the same (#319).
+    def reject_duplicates(out, **ctx)
+      writes = Hash.new(0)
+      (out[:subjects] + out[:unsupported]).each { |entry| writes[entry.id] += 1 }
+      duplicates = out[:subjects].select { |subject| writes[subject.id] > 1 }
+      return if duplicates.empty?
+
+      out[:subjects] -= duplicates
+      duplicates.each do |subject|
+        out[:unsupported] << Unsupported.new(name: subject.name, owner: subject.owner, file: ctx[:file],
+                                             node: subject.node,
+                                             reason: "assigned more than once in this file")
+      end
+    end
+
+    def frozen_literals?(result)
+      result.magic_comments.any? do |comment|
+        comment.key.tr("-", "_").casecmp?("frozen_string_literal") && comment.value.casecmp?("true")
+      end
+    end
+
+    def walk(node, nesting, out, **ctx)
+      return if node.nil?
+
+      case node
+      when Prism::BlockNode, Prism::LambdaNode
+        walk(node.body, nesting, out, **ctx, in_block: true)
+      when Prism::ConstantWriteNode
+        constant_assignment(node, nesting, out, **ctx)
+      when Prism::IfNode, Prism::UnlessNode
+        walk_conditional(node, nesting, out, **ctx)
+      when Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode
+        record_unsupported(out, node, nesting, "a conditional assignment (#{node.operator_loc.slice})", **ctx)
+        walk_children(node, nesting, out, **ctx)
+      when Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode
+        record_unsupported(out, node, nesting, "a namespaced target (#{node.target.slice})", **ctx)
+        walk_children(node, nesting, out, **ctx)
+      # A keyword class or module re-enters the lexical scope: its constants
+      # are ordinary subjects even inside a block, and factory scopes never
+      # join their paths (#352).
+      when Prism::ModuleNode, Prism::ClassNode
+        kind = node.is_a?(Prism::ModuleNode) ? :module : :class
+        scope = Scope.new(kind: kind, path: node.constant_path.slice)
+        walk(node.body, lexical_nesting(nesting) + [scope], out, **ctx, in_block: false)
+      when Prism::SingletonClassNode
+        walk_singleton_class(node, nesting, out, **ctx)
+      else
+        walk_children(node, nesting, out, **ctx)
+      end
+    end
+
+    # A write under a condition may never run: mutating its literal cannot
+    # change the constant when the guard skips the write (#319).
+    def walk_conditional(node, nesting, out, **ctx)
+      walk(node.predicate, nesting, out, **ctx)
+      walk(node.statements, nesting, out, **ctx, guarded: true)
+      walk(node.respond_to?(:subsequent) ? node.subsequent : node.else_clause, nesting, out, **ctx,
+           guarded: true)
+    end
+
+    def walk_children(node, nesting, out, **ctx)
+      node.compact_child_nodes.each { |child| walk(child, nesting, out, **ctx) }
+    end
+
+    # `class << self` opens the attached class's singleton scope: constants
+    # assigned there bind on the singleton class, so the scope joins the
+    # nesting and owner_path renders it "<attached>.singleton_class" (#380,
+    # mirroring SubjectFinder). Unlike a keyword class, `class << self`
+    # does not reset in_block: a block's runtime self is unknowable at
+    # parse time (an `included do` block runs with the including class as
+    # self), so its constants stay conservatively skipped inside a block.
+    # A non-self receiver, a nested singleton class or the top level has no
+    # statically nameable singleton: the enclosing nesting stays.
+    def walk_singleton_class(node, nesting, out, **ctx)
+      unless node.expression.is_a?(Prism::SelfNode) && nesting.any? && !nesting.last.sclass?
+        return walk_children(node, nesting, out, **ctx)
+      end
+
+      walk(node.body, nesting + [Scope.new(kind: :sclass, path: "self")], out, **ctx)
+    end
+
+    def constant_assignment(node, nesting, out, **ctx)
+      return walk_factory(node, nesting, out, **ctx) if factory_scope?(node)
+
+      literal = literal_value(node.value)
+      reason = unsupported_reason(node, literal, **ctx)
+      if reason
+        record_unsupported(out, node, nesting, reason, **ctx)
+        walk_children(node, nesting, out, **ctx)
+        return
+      end
+
+      subject = ConstantSubject.new(name: node.name, owner: owner_path(nesting), file: ctx[:file], node: node,
+                                    literal_node: literal, file_source: ctx[:source], nesting: nesting,
+                                    frozen_literals: ctx[:frozen])
+      subject.skip_reason = "defined inside a block" if ctx[:in_block]
+      out[:subjects] << subject
+      # Another constant can hide in the literal's values (`MAP = { x: (Y = []) }`).
+      walk_children(node, nesting, out, **ctx)
+    end
+
+    # `Point = Data.define(:x) do ... end`: the receiver and arguments stay
+    # in the enclosing scope. The block's body is walked directly, not as a
+    # block, and the factory opens no lexical constant scope: a constant
+    # inside the block binds on the enclosing lexical scope and is an
+    # ordinary subject (#352, mirroring SubjectFinder).
+    def walk_factory(node, nesting, out, **ctx)
+      call = node.value
+      (call.compact_child_nodes - [call.block]).each { |child| walk(child, nesting, out, **ctx) }
+      walk(call.block.body, lexical_nesting(nesting) + [Scope.new(kind: :factory, path: node.name.to_s)], out, **ctx)
+    end
+
+    # A factory scope names the class being built but opens no lexical
+    # constant scope, so it never joins a constant's path (#339).
+    def lexical_nesting(nesting)
+      nesting.reject(&:factory?)
+    end
+
+    def unsupported_reason(_node, literal, guarded: false, **)
+      return "guarded by a condition" if guarded
+      return "its value is not a hash or array literal" if literal.nil?
+
+      nil
+    end
+
+    # `Point = Data.define(...) do ... end`: only the four core factories
+    # count, called on the bare constant (mirrors SubjectFinder).
+    def factory_scope?(node)
+      call = node.value
+      return false unless call.is_a?(Prism::CallNode) && call.block.is_a?(Prism::BlockNode)
+      return false unless call.receiver.is_a?(Prism::ConstantReadNode)
+
+      CLASS_FACTORIES[call.receiver.name] == call.name
+    end
+
+    # The hash or array literal behind the value, looking through `.freeze`
+    # calls only: any other receiver chain transforms the value, so the
+    # literal is not what the constant holds.
+    def literal_value(value)
+      value = value.receiver while value.is_a?(Prism::CallNode) && value.name == :freeze &&
+                                   value.arguments.nil? && value.block.nil? && value.receiver
+      value if value.is_a?(Prism::HashNode) || value.is_a?(Prism::ArrayNode)
+    end
+
+    def record_unsupported(out, node, nesting, reason, **ctx)
+      # A bare target takes the lexical owner. A ROOTED qualified target names
+      # its constant absolutely ("::RULES" is RULES anywhere). An UNROOTED one
+      # resolves through the lexical scope: "Shop::RULES" inside
+      # `module Outer; module Shop` writes Outer::Shop::RULES. Every id on the
+      # write's scope chain is a candidate, so each goes on the ambiguous list
+      # for demotion after the walk; over-matching only demotes a subject.
+      if node.respond_to?(:name)
+        name = node.name
+        owner = owner_path(nesting)
+      else
+        name = node.target.slice.sub(/\A::/, "")
+        owner = nil
+        unless node.target.slice.start_with?("::")
+          nesting.length.downto(0) do |depth|
+            prefix = owner_path(nesting[0...depth])
+            out[:ambiguous] << (prefix ? "#{prefix}::#{name}" : name)
+          end
+        end
+      end
+      out[:unsupported] << Unsupported.new(name: name, owner: owner, file: ctx[:file],
+                                           node: node, reason: reason)
+    end
+
+    # A subject whose id an unrooted qualified write may resolve to cannot be
+    # mutated safely: replaying the file lets that write overwrite it.
+    def demote_ambiguous(out, **ctx)
+      return if out[:ambiguous].empty?
+
+      poisoned = out[:subjects].select { |subject| out[:ambiguous].include?(subject.id) }
+      out[:subjects] -= poisoned
+      poisoned.each do |subject|
+        out[:unsupported] << Unsupported.new(name: subject.name, owner: subject.owner, file: ctx[:file],
+                                             node: subject.node,
+                                             reason: "an unrooted qualified write may overwrite it")
+      end
+    end
+
+    # Lexical path of the enclosing class/module, or nil at the top level.
+    # A singleton-class scope renders as "<attached>.singleton_class":
+    # constants assigned in `class << self` bind on the singleton class,
+    # not on the attached class (#380). Factory scopes open no lexical
+    # constant scope, but a factory's block is class_eval'd, so a `class <<
+    # self` directly inside one attaches to the factory's class.
+    def owner_path(nesting)
+      return nil if nesting.empty?
+
+      parts = []
+      factory_path = nil
+      nesting.each do |scope|
+        if scope.sclass?
+          # `self` is the innermost named scope: the factory's class inside a
+          # factory block (its block is class_eval'd), the attached class or
+          # module otherwise.
+          if factory_path
+            # factory_path carries the full prefix already: replace, never
+            # append, or the enclosing scope doubles (#395).
+            parts = ["#{factory_path}.singleton_class"]
+          elsif parts.any?
+            parts[-1] = "#{parts.last}.singleton_class"
+          end
+          factory_path = nil
+        elsif scope.factory?
+          factory_path = (parts + [scope.path.delete_prefix("::")]).join("::")
+        else
+          parts.clear if scope.path.start_with?("::")
+          parts << scope.path.delete_prefix("::")
+          factory_path = nil
+        end
+      end
+      parts.empty? ? nil : parts.join("::")
+    end
+  end
+end

data/lib/saboteur/coverage_reads.rb

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # Every Coverage.result read goes through here. With the methods report
+  # on, the C call hashes each method owner and trusts the return type, so
+  # a loaded class whose `hash` does not return an Integer (forem's
+  # ReactionCategory, #564) makes every read raise TypeError - a "please
+  # report it" crash for what is a bug in the application's code. Refuse
+  # instead. The handler runs no app code (an ObjectSpace scan would call
+  # #hash/#name on hostile classes) and the error's backtrace names no
+  # owning class, so the message stays generic rather than accusing one.
+  module CoverageReads
+    module_function
+
+    def result(stop:, clear:)
+      Coverage.result(stop:, clear:)
+    rescue TypeError => e
+      raise Error, diagnostic(e)
+    end
+
+    def diagnostic(error)
+      "Coverage.result raised TypeError (#{error.message}): Coverage's method report hashes every " \
+        "method owner and trusts the result, and a loaded class whose #hash does not return an " \
+        "Integer (Ruby's #hash contract) breaks it. This is a bug in the application's code, " \
+        "not in saboteur."
+    end
+  end
+end

data/lib/saboteur/dirty_tree_warning.rb

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# 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
+  # 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.
+  #
+  # Each change lands in exactly one group, so the groups add up to the
+  # count: saboteur setup files first (the config file the run reads, a
+  # trial Gemfile and its lock), then the mutation scope (a file the
+  # configured include and exclude select, the way Config#included_files
+  # does), then the rest. A path the patterns match also counts, so a
+  # deleted source is still inside the scope. The scope is the configured
+  # one: --since, --subject and source operands narrow a run further, after
+  # this warning.
+  class DirtyTreeWarning
+    SHOWN_PATHS = 5
+    MATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+    ADVICE = "Mutants run your code and could alter or delete files; " \
+             "run on a clean, committed tree or a CI checkout."
+
+    # The warning text for the run's working tree, or nil on a clean or
+    # unknown tree. The root is physical (realpath), like the paths
+    # Config#included_files returns.
+    def self.for(config, config_path:, gemfile: ENV.fetch("BUNDLE_GEMFILE", nil))
+      state = WorkingTree.new(config.root, ignored: config.output_paths).state
+      root = File.realpath(config.root)
+      new(state, included: relative(config.included_files, root), include: config["include"],
+                 exclude: config["exclude"], root: root,
+                 setup_files: setup_files(root, config_path: config_path, gemfile: gemfile)).to_s
+    end
+
+    # Files a trial of saboteur adds, relative to the root: the config file
+    # the run reads and, when BUNDLE_GEMFILE names a Gemfile other than the
+    # root's own, that Gemfile and its lock. Each file is compared by its
+    # physical path, so a /var spelling of a /private/var root still
+    # matches (#503).
+    def self.setup_files(root, config_path:, gemfile:)
+      files = [physical(File.expand_path(config_path || Config::FILE, root))]
+      trial = gemfile && physical(File.expand_path(gemfile, root))
+      files.push(trial, lockfile_for(trial)) if trial && trial != File.join(root, "Gemfile")
+      relative(files, root)
+    end
+
+    # Bundler's own rule, the same one preflight's execution inputs check
+    # against Bundler.default_lockfile: a gems.rb trial locks to gems.locked
+    # next to it; every other name gets ".lock" appended.
+    def self.lockfile_for(gemfile)
+      return File.join(File.dirname(gemfile), "gems.locked") if File.basename(gemfile) == "gems.rb"
+
+      "#{gemfile}.lock"
+    end
+
+    # git status paths are relative to the root, so the patterns are too:
+    # Dir.glob accepts a leading ./ or an absolute path under the root and
+    # File.fnmatch? does not (#503). A pattern outside the root stays
+    # absolute and matches no git path.
+    def self.relative_patterns(patterns, root)
+      patterns.map { |pattern| File.expand_path(pattern, root).delete_prefix(File.join(root, "")) }
+    end
+
+    # The path with its directory resolved, so a file that does not exist
+    # yet still gets the physical spelling of where it would be.
+    def self.physical(path)
+      File.join(File.realpath(File.dirname(path)), File.basename(path))
+    rescue SystemCallError
+      path
+    end
+
+    # A file outside the root keeps its absolute path, which no
+    # root-relative git path can equal.
+    def self.relative(files, root)
+      prefix = File.join(root, "")
+      files.map { |file| file.delete_prefix(prefix) }
+    end
+
+    private_class_method :physical, :relative
+
+    def initialize(state, included:, include:, exclude:, setup_files:, root:)
+      @state = state
+      @included = included.to_set
+      @include = self.class.relative_patterns(include, root)
+      @exclude = self.class.relative_patterns(exclude, root)
+      @setup_files = setup_files
+    end
+
+    def to_s
+      return unless @state.dirty
+
+      setup, rest = @state.changes.partition { |change| @setup_files.include?(change.path) }
+      scope, outside = rest.partition { |change| in_scope?(change.path) }
+      [summary(setup, scope, outside), named("inside the mutation scope", scope), named("setup files", setup),
+       "  #{ADVICE}"].compact.join("\n")
+    end
+
+    private
+
+    def summary(setup, scope, outside)
+      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(', ')}."
+    end
+
+    def counted(label, changes)
+      tracked = changes.count(&:tracked)
+      "#{changes.size} #{label} (#{tracked} tracked, #{changes.size - tracked} untracked)"
+    end
+
+    def named(label, changes)
+      return if changes.empty?
+
+      paths = changes.first(SHOWN_PATHS).map(&:path).join(", ")
+      more = changes.size - SHOWN_PATHS
+      "  #{label}: #{paths}#{" and #{more} more" if more.positive?}"
+    end
+
+    def in_scope?(path)
+      @included.include?(path) || (path.end_with?(".rb") && matches?(@include, path) && !matches?(@exclude, path))
+    end
+
+    def matches?(patterns, path)
+      patterns.any? { |pattern| File.fnmatch?(pattern, path, MATCH_FLAGS) }
+    end
+  end
+end

data/lib/saboteur/doctor.rb

@@ -98,6 +98,15 @@ module Saboteur
       else
         @out.puts "Sandbox: #{Engine::SandboxPolicy.sandbox_gap(abi)}; " \
                   "children would run with the hazard guard and canary only"
+        if RUBY_PLATFORM.match?(/darwin/i) && @config["sandbox"] == "seatbelt"
+          @out.puts %(Seatbelt (opt-in, #436): probe #{Execution::Seatbelt.probe} - capability probe only, ) \
+                    "not verified isolation"
+        elsif RUBY_PLATFORM.match?(/darwin/i)
+          @out.puts "macOS: mutants run unsandboxed (Landlock is Linux-only) - a container contains " \
+                    "filesystem writes outside the project"
+          @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
       end
     end
 

data/lib/saboteur/engine/baseline_guard.rb

@@ -4,6 +4,7 @@
 require "json"
 require "fileutils"
 require_relative "../text"
+require_relative "../frameworks/sqlite_memory_database"
 
 module Saboteur
   class Engine
@@ -52,7 +53,7 @@ module Saboteur
           announce_first_pass_cost(number, started)
           unless data["passed"] && data["failed"].empty?
             refuse(number,
-                   "the suite failed: #{Array(data['failed']).join(', ')}")
+                   with_hint("the suite failed: #{Array(data['failed']).join(', ')}", data))
           end
           executed = data["executed"]
           refuse(number, "executed tests do not match the loaded suite") unless
@@ -85,16 +86,24 @@ module Saboteur
       end
 
       # Once the first pass is timed, the total cost stops being a guess:
-      # the remaining full passes cost roughly the same each.
+      # the remaining full passes cost roughly the same each. full_passes
+      # includes the cold-cache coverage build (#260), so name what actually
+      # remains: with baseline_passes 1 the one remaining pass is the coverage
+      # build, not another baseline check (#465).
       def announce_first_pass_cost(number, started)
         return unless number == 1
 
-        remaining = @full_passes - number
-        return if remaining.zero?
+        coverage_pending = @full_passes > @config["baseline_passes"]
+        remaining = @full_passes - number - (coverage_pending ? 1 : 0)
+        return if remaining.zero? && !coverage_pending
 
         elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round
-        @diagnostics.inform("baseline check #{number} took #{elapsed} s; about #{elapsed * remaining} s left for " \
-                            "the remaining #{remaining} full #{remaining == 1 ? 'pass' : 'passes'} at that rate")
+        work = []
+        work << "the remaining #{remaining} full #{remaining == 1 ? 'pass' : 'passes'}" if remaining.positive?
+        work << "the coverage map build" if coverage_pending
+        total = remaining + (coverage_pending ? 1 : 0)
+        @diagnostics.inform("baseline check #{number} took #{elapsed} s; about #{elapsed * total} s left for " \
+                            "#{work.join(' and ')} at that rate")
       end
 
       # An admitted pass still gets only the time left in the run budget:
@@ -117,6 +126,24 @@ module Saboteur
                                   "phase timeout)"
       end
 
+      # A containment limit stopping a healthy suite means the limit, not
+      # the suite: name the knob and its current value, like the sqlite
+      # :memory: hint (#387), so the user is not sent debugging a green
+      # suite (#459).
+      def stopped_reason(result)
+        reason = "the suite stopped: #{result.stopped_by} (#{result.detail})"
+        case result.stopped_by
+        when :processes
+          "#{reason}. If this suite forks heavily by design, raise the limit with " \
+          "c.max_processes (currently #{@config['max_processes']})"
+        when :memory
+          "#{reason}. If this suite legitimately needs more memory, raise the limit with " \
+          "c.max_memory_mb (currently #{@config['max_memory_mb']} MB)"
+        else
+          reason
+        end
+      end
+
       def check(number)
         Execution::ForkReadiness.prepare_heap
         heartbeat = @diagnostics.progress_heartbeat("baseline check #{number}").watch(log_path(number))
@@ -126,14 +153,14 @@ module Saboteur
           record(writer, number)
         end
         refuse_budget_stop(number, admitted) if budget_stopped?(result, admitted)
-        refuse(number, "the suite stopped: #{result.stopped_by} (#{result.detail})") if result.stopped_by
+        refuse(number, stopped_reason(result)) if result.stopped_by
         # Before the payload checks: a child killed by a signal (the OOM
         # killer, say) writes nothing, and the signal is the explanation. A
         # child the supervisor itself killed after it had reported is not a
         # failure: its payload is checked below.
         refuse(number, unsuccessful_exit(result.exit_status, result.memory_pressure)) if result.child_failed?
         refuse(number, "the child did not report a result") if result.payload.empty?
-        refuse(number, "the suite left child processes behind") if result.leftover_pids.any?
+        refuse(number, leftover_message(result), excerpt: false) if result.leftover_pids.any?
         parse_result(number, result.payload)
       end
 
@@ -151,7 +178,7 @@ module Saboteur
       def parse_result(number, payload)
         data = JSON.parse(payload)
         refuse(number, "the child reported an invalid result") unless data.is_a?(Hash)
-        refuse(number, data["error"]) if data["error"]
+        refuse(number, with_hint(data["error"], data)) if data["error"]
         refuse(number, "the child reported invalid test results") unless valid_result?(data)
         data
       rescue JSON::ParserError
@@ -172,21 +199,42 @@ module Saboteur
         @hooks.run(:after_fork)
         Kernel.srand(@config["seed"])
         result = @integration.run_baseline(seed: @config["seed"])
-        writer.write(JSON.generate(passed: result.passed, failed: result.failed_ids, executed: result.executed_ids))
+        payload = { passed: result.passed, failed: result.failed_ids, executed: result.executed_ids }
+        payload[:hint] = Frameworks::SqliteMemoryDatabase.fork_loss_hint unless result.passed
+        writer.write(JSON.generate(payload))
       rescue Exception => e # rubocop:disable Lint/RescueException
-        writer.write(JSON.generate(error: "#{e.class}: #{e.message}"))
+        writer.write(JSON.generate(error: "#{e.class}: #{e.message}",
+                                   hint: Frameworks::SqliteMemoryDatabase.fork_loss_hint))
       ensure
         writer.close
       end
 
+      # A child that recognises its own failure shape (an empty sqlite
+      # :memory: database after the fork, #387) says how to fix it.
+      def with_hint(reason, data)
+        data["hint"] ? "#{reason}. #{data['hint']}" : reason
+      end
+
       def log_path(number)
         File.join(@config.path("cache_dir"), "baseline-#{number}.log")
       end
 
-      def refuse(number, reason)
+      # Leftover children are a pass-with-leaks verdict, not a suite
+      # failure: the message names the leaked processes (the supervisor's
+      # pre-kill notes) and skips the log excerpt, which holds only RSpec
+      # output and can never show them (#486).
+      def leftover_message(result)
+        notes = result.leftover_notes
+        detail = notes.empty? ? result.leftover_pids.join(", ") : notes.join(", ")
+        count = result.leftover_pids.size
+        "the suite passed but left #{count} child #{count == 1 ? 'process' : 'processes'} behind: #{detail}"
+      end
+
+      def refuse(number, reason, excerpt: true)
         raise Error, "baseline check #{number} failed at seed #{@config['seed']}: #{reason}. " \
-                     "#{failure_excerpt(number)}See the full log at #{log_path(number)}. Fix the suite or its " \
-                     "setup, then run saboteur again with the same seed. No mutants were started."
+                     "#{failure_excerpt(number) if excerpt}See the full log at #{log_path(number)}. " \
+                     "Fix the suite or its setup, then run saboteur again with the same seed. " \
+                     "No mutants were started."
       end
 
       # The first lines of the failure, inline, so the cause is readable