saboteur 0.6.0 → 0.7.0

data/lib/saboteur/crash_report.rb

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+require "pathname"
+
+module Saboteur
+  # Last-resort crash reporting, shared by the CLI's StandardError rescue
+  # and the exe-level wrapper: one bounded line on stderr, the full
+  # backtrace in a log file the line names, the backtrace on stderr with
+  # --verbose, and the same failure as agent JSON when an agent listens.
+  # Always returns EXIT_TOOL.
+  module CrashReport
+    ISSUES_URL = "https://github.com/vamsipavanmahesh/saboteur/issues"
+
+    # Same value as CLI::EXIT_TOOL, kept local so the reporter still works
+    # when the CLI itself never finished loading.
+    EXIT_TOOL = 3
+
+    # The crash log's file name under the run's cache dir; the runner reads
+    # it back to explain a nested run's crash in the failure detail (#296).
+    LOG_NAME = "internal-error.log"
+
+    module_function
+
+    def call(error, verbose:, agent:, err:, out:, log_path: nil)
+      summary = "internal error (#{error.class}: #{one_line(error.message)})"
+      line = "saboteur: #{summary} - please report it: #{ISSUES_URL}"
+      written = write_log(log_path, error)
+      line = "#{line}; full backtrace: #{display_path(written)}" if written
+      err.puts(line)
+      err.puts(full_text(error)) if verbose
+      out.print(agent_json(summary)) if agent
+      EXIT_TOOL
+    end
+
+    # A crash message can span lines or carry bytes that are invalid in
+    # UTF-8 (a LANG=C failure, say); the one-line diagnostic must survive
+    # both, and stay one bounded line.
+    def one_line(message)
+      text = scrub(message).gsub(/\s+/, " ").strip
+      text.length > 160 ? "#{text[0...160]}..." : text
+    end
+
+    # Class, full message and backtrace, scrubbed so locale-invalid bytes
+    # cannot corrupt the log or the terminal.
+    def full_text(error)
+      (["#{error.class}: #{scrub(error.message)}"] + Array(error.backtrace).map { |frame| scrub(frame) }).join("\n")
+    end
+
+    # Writes the log next to the other run state; returns the written path,
+    # or nil when the log cannot be written - the crash itself must still
+    # be reported, so an unwritable directory is not a second failure.
+    # Reporter::Agent.failure's payload, reproduced minimally for crashes
+    # before the CLI's reporter files load: same schema and pretty rendering;
+    # the summary is already normalized, so no message cap is needed here.
+    def agent_json(summary)
+      payload =
+        if defined?(Reporter::Agent)
+          Reporter::Agent.failure(summary, EXIT_TOOL)
+        else
+          { version: 1, status: "error", verdict: "tool_failure", exitCode: EXIT_TOOL,
+            message: summary, next: { help: "saboteur help run" } }
+        end
+      "#{JSON.pretty_generate(payload)}\n"
+    end
+
+    def write_log(log_path, error)
+      return nil unless log_path
+
+      # The primary path is user-configured but still predictable: without
+      # O_NOFOLLOW a planted symlink would redirect the truncate/chmod, and
+      # without O_NONBLOCK a planted FIFO would block the open. Where the
+      # platform lacks either, only the EXCL-created temp fallback is safe
+      # (#296).
+      if safe_log_io?
+        begin
+          FileUtils.mkdir_p(File.dirname(log_path))
+          # Private like the temp fallback: the runner only reads logs with
+          # no group/other bits, from the same no-follow fd (#296).
+          flags = File::CREAT | File::WRONLY | File::TRUNC | nofollow_flag | nonblock_flag
+          File.open(log_path, flags, 0o600) do |file|
+            file.chmod(0o600)
+            file.write("#{full_text(error)}\n")
+          end
+          return log_path
+        rescue SystemCallError, IOError
+          # Fall through to the temp fallback.
+        end
+      end
+      write_tmp_log(error)
+    end
+
+    # The fallback is computed lazily, only once the primary write failed:
+    # an eager tmp_log_path call could itself raise (Dir.tmpdir finds no
+    # usable dir) and mask the crash it was meant to log (#296).
+    #
+    # The fallback path is predictable and lives in a shared directory, so
+    # it is created privately: CREAT|EXCL|WRONLY|NOFOLLOW never follows or
+    # overwrites a pre-existing file or symlink, and the mode pins the log
+    # to 0600. A taken or hostile path means no log - the crash report
+    # itself must still go out, so every failure here degrades to nil.
+    def write_tmp_log(error)
+      File.open(tmp_log_path, File::CREAT | File::EXCL | File::WRONLY | nofollow_flag, 0o600) do |file|
+        file.write("#{full_text(error)}\n")
+      end
+      tmp_log_path
+    rescue SystemCallError, IOError, ArgumentError
+      nil
+    end
+
+    # O_NOFOLLOW where the platform has it (every CI target does).
+    def nofollow_flag
+      File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0
+    end
+
+    # O_NONBLOCK where the platform has it (every CI target does).
+    def nonblock_flag
+      File.const_defined?(:NONBLOCK) ? File::NONBLOCK : 0
+    end
+
+    # The private crash-log write/read needs both flags: without O_NOFOLLOW
+    # a planted symlink redirects the open, without O_NONBLOCK a planted
+    # FIFO blocks it. Where either is missing, the log is omitted rather
+    # than opened unsafely (#296).
+    def safe_log_io?
+      File.const_defined?(:NOFOLLOW) && File.const_defined?(:NONBLOCK)
+    end
+
+    # Where the log lands when a configured cache dir is not writable - a
+    # sandboxed child holds the project read-only, but the system temp dir is
+    # granted (#296). Only a configured log path falls back: cache_dir = nil
+    # still means no log at all. Keyed by pid so parallel children never
+    # share a file; the runner reads the same path back in the same process.
+    def tmp_log_path(pid: Process.pid)
+      File.join(Dir.tmpdir, "saboteur-#{pid}-#{LOG_NAME}")
+    end
+
+    # The message names the log; relative to the working directory when it
+    # sits inside it, so the line stays short.
+    def display_path(path)
+      relative = Pathname(path).relative_path_from(Pathname(Dir.pwd)).to_s
+      relative.start_with?("..") ? path : relative
+    rescue ArgumentError
+      path
+    end
+
+    def scrub(string)
+      string.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?")
+    end
+  end
+end

data/lib/saboteur/custom_map.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "text"
+
 module Saboteur
   # Explicit source-file -> spec-file mapping from config/saboteur_custom_map.rb:
   #
@@ -109,7 +111,7 @@ module Saboteur
     def duplicate_keys(path)
       seen = Hash.new(0)
       File.readlines(path).each do |line|
-        seen[::Regexp.last_match(1)] += 1 if line =~ /^\s*"(.+?)"\s*=>/
+        seen[::Regexp.last_match(1)] += 1 if Text.utf8(line) =~ /^\s*"(.+?)"\s*=>/
       end
       seen.select { |_, count| count > 1 }.keys
     end

data/lib/saboteur/doctor.rb

@@ -3,6 +3,8 @@
 
 require "coverage"
 require_relative "baseline_health"
+require_relative "engine/sandbox_policy"
+require_relative "execution/sandbox"
 
 module Saboteur
   # Reports the current environment, never mutations. The two unchanged suite
@@ -27,7 +29,8 @@ module Saboteur
       @out.puts "Rails: #{@config['rails'] ? 'enabled' : 'disabled'}"
       check_database_hosts
       @out.puts "SimpleCov: #{defined?(::SimpleCov) ? 'present; start suppressed for this process' : 'not loaded'}"
-      check_coverage
+      verify_coverage
+      check_sandbox
       check_suite(integration, hooks)
       true
     end
@@ -63,15 +66,51 @@ module Saboteur
             "doctor supports the rspec integration; set integration: rspec"
     end
 
+    # Printed once; verified twice. Boot must not wake coverage up, so the
+    # post-boot check re-reads the state without printing a second line.
     def check_coverage
       state = Coverage.state
       @out.puts "Coverage: #{state}"
+      verify_coverage(state)
+    end
+
+    def verify_coverage(state = Coverage.state)
       return if Coverage.supported?(:lines) && Coverage.supported?(:methods) && state == :suspended
 
       raise Error, "Coverage must be suspended with line and method support before boot; use the saboteur " \
                    "executable, disable SimpleCov and remove other Coverage.start calls"
     end
 
+    # A kernel capability probe, not verified isolation: what the kernel
+    # would let mutant children do, and what the run does with that - the
+    # engine's sandbox policy owns the refusal or degradation itself.
+    def check_sandbox
+      if @config["sandbox"] == false
+        @out.puts "Sandbox: off (c.sandbox = false)"
+        return
+      end
+      abi = sandbox_abi
+      if abi >= 3
+        @out.puts "Sandbox: kernel Landlock ABI #{abi} - capability probe only, not verified isolation"
+      elsif @config["sandbox"] == "strict"
+        @out.puts "Sandbox: #{Engine::SandboxPolicy.sandbox_gap(abi)}; " \
+                  'c.sandbox = "strict" refuses to run - children never run degraded'
+      else
+        @out.puts "Sandbox: #{Engine::SandboxPolicy.sandbox_gap(abi)}; " \
+                  "children would run with the hazard guard and canary only"
+      end
+    end
+
+    # The probe contract the engine's policy already keeps: an errored probe
+    # (EPERM under a seccomp policy, ...) is an actionable tool error, not a
+    # CLI internal error - doctor stays read-only.
+    def sandbox_abi
+      Execution::Sandbox.abi_version
+    rescue SystemCallError => e
+      raise Error, "sandbox is on but the Landlock probe failed (#{e.message}); a run would refuse the same way - " \
+                   "set c.sandbox = false to check without the sandbox"
+    end
+
     # Match against all included source definitions, not the current diff or
     # selected tests. A limited run must not make a valid ignore look stale.
     def check_ignore_subjects

data/lib/saboteur/engine/baseline_guard.rb

@@ -3,6 +3,7 @@
 
 require "json"
 require "fileutils"
+require_relative "../text"
 
 module Saboteur
   class Engine
@@ -10,16 +11,28 @@ module Saboteur
     # or mutation source is used. This catches observed instability, not all
     # possible flaky behaviour.
     class BaselineGuard
+      # How many unchanged-suite checks actually completed and validated:
+      # the number of order comparisons a run can claim is one less.
+      attr_reader :completed_passes
+
       EXCERPT_LINES = 10
       EXCERPT_WIDTH = 200
       EXCERPT_SCAN_LINES = 5000
 
-      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:)
+      # full_passes: every full-suite pass the run will make, including the
+      # coverage build when the cache is cold, so the first timed pass can
+      # price the rest (#260).
+      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, full_passes: 2, between_passes: nil,
+                     timeout_cap: nil)
         @config = config
         @integration = integration
         @hooks = hooks
         @supervisor = supervisor
         @diagnostics = diagnostics
+        @full_passes = full_passes
+        @between_passes = between_passes
+        @timeout_cap = timeout_cap
+        @completed_passes = 0
       end
 
       def call
@@ -27,11 +40,16 @@ module Saboteur
         raise Error, "baseline has no tests. Check rspec_args and the suite filters before running saboteur again." if
           expected.empty?
 
-        @diagnostics.inform("checking the unchanged suite twice (seed #{@config['seed']})")
+        passes = @config["baseline_passes"]
+        @diagnostics.inform(announce(passes))
         previous = nil
-        2.times do |index|
+        passes.times do |index|
+          break if budget_spent?(index)
+
           number = index + 1
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           data = check(number)
+          announce_first_pass_cost(number, started)
           unless data["passed"] && data["failed"].empty?
             refuse(number,
                    "the suite failed: #{Array(data['failed']).join(', ')}")
@@ -41,18 +59,73 @@ module Saboteur
             executed.sort == expected.sort
           refuse(number, "test order changed between baseline checks") if previous && executed != previous
           previous = executed
+          @completed_passes += 1
         end
         nil
       end
 
       private
 
+      # A spent --max-duration budget skips the remaining passes - including
+      # the first, when boot alone already spent it (#245).
+      def budget_spent?(_index)
+        !@between_passes.nil? && @between_passes.call
+      end
+
+      def announce(passes)
+        case passes
+        when 1
+          "checking the unchanged suite once (seed #{@config['seed']}); " \
+          "order stability between passes is not checked (baseline_passes: 1)"
+        when 2
+          "checking the unchanged suite twice (seed #{@config['seed']})"
+        else
+          "checking the unchanged suite #{passes} times (seed #{@config['seed']})"
+        end
+      end
+
+      # Once the first pass is timed, the total cost stops being a guess:
+      # the remaining full passes cost roughly the same each.
+      def announce_first_pass_cost(number, started)
+        return unless number == 1
+
+        remaining = @full_passes - number
+        return if remaining.zero?
+
+        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")
+      end
+
+      # An admitted pass still gets only the time left in the run budget:
+      # without the cap it would overrun a spent --max-duration by its
+      # whole coverage_timeout.
+      def phase_timeout
+        @timeout_cap ? @timeout_cap.call(@config["coverage_timeout"]) : @config["coverage_timeout"]
+      end
+
+      # A pass that hit its deadline only because --max-duration shortened
+      # the admission below the configured phase timeout: the budget ended
+      # the run, the suite is not broken (#296).
+      def budget_stopped?(result, admitted)
+        result.stopped_by == :timeout && admitted < @config["coverage_timeout"]
+      end
+
+      def refuse_budget_stop(number, admitted)
+        raise BudgetPhaseTimeout, "the --max-duration budget stopped baseline check #{number} " \
+                                  "(admitted #{admitted.round(1)}s of the #{@config['coverage_timeout']}s " \
+                                  "phase timeout)"
+      end
+
       def check(number)
         Execution::ForkReadiness.prepare_heap
         heartbeat = @diagnostics.progress_heartbeat("baseline check #{number}").watch(log_path(number))
-        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+        admitted = phase_timeout
+        result = @supervisor.run(timeout: admitted, on_tick: heartbeat.method(:tick),
+                                 label: "baseline child died during setup/run") do |writer|
           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
         # Before the payload checks: a child killed by a signal (the OOM
         # killer, say) writes nothing, and the signal is the explanation. A
@@ -129,7 +202,8 @@ module Saboteur
       end
 
       def log_lines(number)
-        File.foreach(log_path(number), chomp: true).first(EXCERPT_SCAN_LINES).reject { |line| line.strip.empty? }
+        File.foreach(log_path(number), chomp: true).first(EXCERPT_SCAN_LINES)
+            .map { |line| Text.utf8(line) }.reject { |line| line.strip.empty? }
       rescue SystemCallError
         []
       end

data/lib/saboteur/engine/boot.rb

@@ -83,10 +83,21 @@ module Saboteur
 
       def load_hooks
         Saboteur.current_hooks = @hooks
-        @config["hooks"].each { |file| load File.expand_path(file, @root) }
+        @config["hooks"].each { |file| load hook_path(file) }
       ensure
         Saboteur.current_hooks = nil
       end
+
+      # Kernel#load does not append .rb the way Kernel#require does, and
+      # doctor accepts the extensionless form (#257), so resolve it the same
+      # way here: the exact path first, then path.rb.
+      def hook_path(file)
+        path = File.expand_path(file, @root)
+        rb = "#{path}.rb"
+        return rb if !File.exist?(path) && File.extname(path).empty? && File.file?(rb)
+
+        path
+      end
     end
   end
 end

data/lib/saboteur/engine/canary.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../text"
 
 module Saboteur
   class Engine
@@ -15,7 +16,9 @@ module Saboteur
       GIT_DIR = ".git"
 
       def initialize(root, cache_dir: ".saboteur")
-        @root = root
+        # Retag losslessly: path bytes are identity here, and later
+        # File.join calls must not mix encodings.
+        @root = Text.utf8_identity(root.to_s)
         @cache_dir = cache_dir.to_s
         @snapshot = inventory
       end
@@ -29,16 +32,40 @@ module Saboteur
 
         of = " of #{subject.id}" if subject
         culprit = digest ? " The most recent mutant, #{digest}#{of}, is the likely cause." : ""
-        raise Saboteur::CanaryTripped,
-              "canary: #{missing.size} watched file(s) vanished from the working tree while mutants ran " \
-              "(first: #{missing.first}).#{culprit} The canary watches tracked files and .git presence " \
-              "and only detects the loss after the fact; it cannot restore anything. Recover from your " \
-              "own backup, a fresh checkout, or a reclone - a deleted .git or uncommitted work is gone " \
-              "unless you have another copy."
+        raise Saboteur::CanaryTripped, message(missing, culprit)
+      end
+
+      # The cheap per-mutant probe (#235): stats the snapshot paths only -
+      # no git, no glob - so it can run after every mutant.
+      def probe
+        @snapshot.reject { |rel| present?(rel) }
+      end
+
+      # Like check!, but for the per-mutant probe: the mutant whose run just
+      # ended is named, never the subject's most recent mutant.
+      def probe!(subject: nil, digest: nil)
+        missing = probe
+        return if missing.empty?
+
+        of = " of #{subject.id}" if subject
+        culprit = digest ? " The mutant that just ran, #{digest}#{of}, is the likely cause." : ""
+        raise Saboteur::CanaryTripped.new(message(missing, culprit), culprit_digest: digest)
       end
 
       private
 
+      def present?(rel)
+        File.exist?(File.join(@root, rel)) || File.symlink?(File.join(@root, rel))
+      end
+
+      def message(missing, culprit)
+        "canary: #{missing.size} watched file(s) vanished from the working tree while mutants ran " \
+          "(first: #{Text.utf8(missing.first)}).#{culprit} The canary watches tracked files and .git presence " \
+          "and only detects the loss after the fact; it cannot restore anything. Recover from your " \
+          "own backup, a fresh checkout, or a reclone - a deleted .git or uncommitted work is gone " \
+          "unless you have another copy."
+      end
+
       def inventory
         files = git? ? git_tracked_files : walk_files
         files << GIT_DIR if File.exist?(File.join(@root, GIT_DIR))
@@ -54,15 +81,19 @@ module Saboteur
         return walk_files unless status.success?
 
         # ls-files reads the index, which still names a deleted file; keep
-        # only paths present in the worktree so a deletion shows up.
-        out.split("\0").reject { |rel| cache_path?(rel) }
+        # only paths present in the worktree so a deletion shows up. Split
+        # the raw bytes first and retag each path losslessly: scrubbing a
+        # raw-byte name would make the File.exist? probe fail and drop the
+        # file from the watch, so its deletion would go unseen.
+        out.b.split("\0".b).map { |rel| Text.utf8_identity(rel) }
+           .reject { |rel| cache_path?(rel) }
            .select { |rel| File.exist?(File.join(@root, rel)) || File.symlink?(File.join(@root, rel)) }
       end
 
       def walk_files
         Dir.glob(File.join(@root, "**", "*"), File::FNM_DOTMATCH)
            .select { |path| File.file?(path) }
-           .map { |path| path.delete_prefix("#{@root}/") }
+           .map { |path| Text.utf8_identity(path).delete_prefix("#{@root}/") }
            .reject { |rel| rel.start_with?("#{GIT_DIR}/") || cache_path?(rel) }
       end
 

data/lib/saboteur/engine/candidate_selection.rb

@@ -6,7 +6,7 @@ module Saboteur
     # Selects a bounded list for each covered subject before workers fork.
     # Subject skips are not mutants and do not enter the mutation score.
     class CandidateSelection
-      attr_reader :skipped_subjects, :selected
+      attr_reader :skipped_subjects, :selected, :unscoped_digests
 
       def initialize(candidates:, map:, limit:, diagnostics:)
         @candidates = candidates
@@ -15,6 +15,7 @@ module Saboteur
         @diagnostics = diagnostics
         @skipped_subjects = {}
         @selected = {}
+        @unscoped_digests = {}
       end
 
       def for(subject, scope: nil)
@@ -25,6 +26,13 @@ module Saboteur
         end
 
         list = @candidates.for(subject)
+        # The full pre-scope digests let IgnoreList#apply tell "mutation gone"
+        # from "mutation scoped out of this run" (#284).
+        if scope
+          @unscoped_digests[subject.id] = list.map do |mutation, _|
+            mutation.digest(subject_start: subject.start_byte, original_source: subject.file_source)
+          end
+        end
         list = scope.restrict(subject, list) if scope
         omitted = list.size - @limit
         if omitted.positive?

data/lib/saboteur/engine/coverage_guard.rb

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Owns the host process's Coverage state across a run: suspends after
+    # boot, and at the end resumes only its own suspension. A CLI process
+    # exits right after, so resume matters to hosts that embed the engine -
+    # a spec, or the dogfood's own coverage-map build (#254).
+    class CoverageGuard
+      def initialize(diagnostics)
+        @diagnostics = diagnostics
+      end
+
+      def suspend
+        @was_running = Coverage.state == :running
+        Coverage.suspend if @was_running
+      end
+
+      # Best-effort: a host that disturbed Coverage mid-run gets a warning,
+      # never a masked run outcome.
+      def resume
+        Coverage.resume if @was_running && Coverage.state == :suspended
+      rescue StandardError => e
+        @diagnostics.warn("coverage resume failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/saboteur/engine/coverage_store.rb

@@ -15,19 +15,29 @@ module Saboteur
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
       LOG = "coverage-build.log"
 
-      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {})
+      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {}, timeout_cap: nil)
         @config = config
         @integration = integration
         @hooks = hooks
         @supervisor = supervisor
         @diagnostics = diagnostics
+        @timeout_cap = timeout_cap
         @load_lines = load_lines
         @root = File.realpath(config.root)
       end
 
+      # True when fetch would reuse the cached map instead of running the
+      # suite pass that builds it: lets the run announce the real number of
+      # full passes up front (#260). Loads the map with the same validation
+      # fetch uses and retains it, so a corrupt or truncated cache announces
+      # a build pass, not a reuse it cannot keep.
+      def reusable?(files)
+        !cached_map(files).nil?
+      end
+
       def fetch(files)
-        path = File.join(@config.path("cache_dir"), "coverage-#{cache_key(files)}.json")
-        cached = @config["cache"] ? Selection::CoverageMap.load(path) : nil
+        path = cache_path(files)
+        cached = cached_map(files)
         return refuse_empty_map(cached, files) if cached
 
         map = refuse_empty_map(build(files), files)
@@ -39,6 +49,16 @@ module Saboteur
 
       private
 
+      def cache_path(files)
+        File.join(@config.path("cache_dir"), "coverage-#{cache_key(files)}.json")
+      end
+
+      def cached_map(files)
+        return nil unless @config["cache"]
+
+        @cached_map ||= Selection::CoverageMap.load(cache_path(files))
+      end
+
       def cache_key(files)
         inputs = JSON.generate(CACHE_INPUTS.to_h { |key| [key, @config[key]] })
         all = files + @integration.test_files + SuiteFiles.new(@config).files + lockfiles
@@ -49,6 +69,12 @@ module Saboteur
         LOCKFILES.map { |file| File.join(@root, file) }.select { |file| File.file?(file) }
       end
 
+      # An admitted build still gets only the time left in the run budget
+      # (see BaselineGuard#phase_timeout).
+      def build_timeout
+        @timeout_cap ? @timeout_cap.call(@config["coverage_timeout"]) : @config["coverage_timeout"]
+      end
+
       def build(files)
         unless Coverage.respond_to?(:state) && Coverage.state == :suspended
           raise Error, "Coverage is #{Coverage.state}; saboteur must set it up before the app loads. " \
@@ -61,13 +87,16 @@ module Saboteur
         # reduce later copying of shared pages.
         Execution::ForkReadiness.prepare_heap
         heartbeat = @diagnostics.progress_heartbeat("building coverage map").watch(log_path)
-        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+        admitted = build_timeout
+        result = @supervisor.run(timeout: admitted, on_tick: heartbeat.method(:tick),
+                                 label: "coverage child died during the map build") do |writer|
           record(writer, files)
         end
-        map_from(result)
+        map_from(result, admitted)
       end
 
-      def map_from(result)
+      def map_from(result, admitted = @config["coverage_timeout"])
+        raise_budget_stop(admitted) if budget_stopped?(result, admitted)
         raise Error, "coverage map build stopped: #{result.detail}" if result.stopped_by
         raise Error, "coverage map build failed: #{died(result.exit_status)}" if result.payload.empty?
 
@@ -77,6 +106,19 @@ module Saboteur
         with_parent_load_lines(Selection::CoverageMap.from_json(result.payload))
       end
 
+      # A build that hit its deadline only because --max-duration shortened
+      # the admission below the configured phase timeout: the budget ended
+      # the run, the suite is not broken (see BaselineGuard#budget_stopped?).
+      def budget_stopped?(result, admitted)
+        result.stopped_by == :timeout && admitted < @config["coverage_timeout"]
+      end
+
+      def raise_budget_stop(admitted)
+        raise BudgetPhaseTimeout, "the --max-duration budget stopped the coverage map build " \
+                                  "(admitted #{admitted.round(1)}s of the #{@config['coverage_timeout']}s " \
+                                  "phase timeout)"
+      end
+
       # The parent's load lines merge into the freshly built map: the forked
       # build child cannot inherit the parent's Coverage counters.
       def with_parent_load_lines(map)