saboteur 0.3.0 → 0.4.0

data/lib/saboteur/engine/baseline_guard.rb

@@ -45,15 +45,32 @@ module Saboteur
 
       def check(number)
         Execution::ForkReadiness.prepare_heap
-        result = @supervisor.run(timeout: @config["coverage_timeout"]) { |writer| record(writer, number) }
+        heartbeat = @diagnostics.progress_heartbeat("baseline check #{number}")
+        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+          record(writer, number)
+        end
         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.
+        if result.exit_status.is_a?(Process::Status) && !result.exit_status.success?
+          refuse(number, unsuccessful_exit(result.exit_status))
+        end
         refuse(number, "the child did not report a result") if result.payload.empty?
-        refuse(number, "the child exited unsuccessfully") if
-          result.exit_status.is_a?(Process::Status) && !result.exit_status.success?
         refuse(number, "the suite left child processes behind") if result.leftover_pids.any?
         parse_result(number, result.payload)
       end
 
+      # A signaled child (the OOM killer, say) can leave an empty log,
+      # which reads like a suite failure; name the signal and hint the
+      # likely cause instead.
+      def unsuccessful_exit(status)
+        return "the child exited with status #{status.exitstatus}" unless status.signaled?
+
+        signal = "SIG#{Signal.signame(status.termsig)}"
+        hint = signal == "SIGKILL" ? " - possible OOM, check memory" : ""
+        "the child was killed by #{signal}#{hint}"
+      end
+
       def parse_result(number, payload)
         data = JSON.parse(payload)
         refuse(number, "the child reported an invalid result") unless data.is_a?(Hash)

data/lib/saboteur/engine/boot.rb

@@ -62,6 +62,7 @@ module Saboteur
         @rails = rails = Frameworks::Rails.new(@config, @hooks) if @config["rails"]
         rails&.before_boot
         @hooks.run(:before_boot)
+        add_spec_to_load_path if @config["rails"]
         @config["require"].each { |file| require File.expand_path(file, @root) }
         integration = Integration.fetch(@config["integration"]).new(@config)
         integration.setup
@@ -72,6 +73,14 @@ module Saboteur
 
       private
 
+      # rspec puts spec/ on the load path, so a boot file under spec/ (a
+      # dummy app's rails_helper, say) can require its siblings. Match
+      # that, or the same require list fails to load.
+      def add_spec_to_load_path
+        path = File.join(@root, "spec")
+        $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
+      end
+
       def load_hooks
         Saboteur.current_hooks = @hooks
         @config["hooks"].each { |file| load File.expand_path(file, @root) }

data/lib/saboteur/engine/coverage_store.rb

@@ -27,9 +27,9 @@ module Saboteur
       def fetch(files)
         path = File.join(@config.path("cache_dir"), "coverage-#{cache_key(files)}.json")
         cached = @config["cache"] ? Selection::CoverageMap.load(path) : nil
-        return cached if cached
+        return refuse_empty_map(cached, files) if cached
 
-        map = build(files)
+        map = refuse_empty_map(build(files), files)
         map.save(path)
         map
       end
@@ -52,11 +52,15 @@ module Saboteur
                        "Run through the saboteur executable and disable SimpleCov for the run."
         end
 
-        @diagnostics.inform("building coverage map (runs the whole suite once)")
+        scope = @config["tests"].empty? ? "the whole suite" : "the selected specs"
+        @diagnostics.inform("building coverage map (runs #{scope} once)")
         # The suite child forked next inherits this heap; pack it first, to
         # reduce later copying of shared pages.
         Execution::ForkReadiness.prepare_heap
-        result = @supervisor.run(timeout: @config["coverage_timeout"]) { |writer| record(writer, files) }
+        heartbeat = @diagnostics.progress_heartbeat("building coverage map")
+        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+          record(writer, files)
+        end
         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?
 
@@ -66,6 +70,29 @@ module Saboteur
         Selection::CoverageMap.from_json(result.payload)
       end
 
+      # A whole-suite build that records no line in any included file fails
+      # the run (exit 3): usually the setup hid the app from Coverage
+      # (Bootsnap's compile cache is the default Rails case); it can also
+      # mean no test in the suite exercises any included file. Either way a
+      # run on this map would test nothing, and exit 0 would lie. With
+      # explicit tests (--test) an empty map is a legitimate outcome
+      # instead: the user narrowed the suite to specs that may not touch
+      # these sources, so the map passes with a warning. Applies to a cached
+      # map too, so a map cached before this check cannot keep a run green,
+      # and the guard runs before saving, so an empty map is never cached.
+      def refuse_empty_map(map, files)
+        return map if files.empty? || map.lines.any? { |_file, by_line| by_line.any? }
+
+        if @config["tests"].empty?
+          raise Error, "Coverage recorded no lines in #{files.size} included files during a whole-suite " \
+                       "build. Is Bootsnap's compile cache on? If not, no test may exercise these files. " \
+                       "Run `saboteur doctor`."
+        end
+        @diagnostics.warn("Coverage recorded no lines in #{files.size} included files; " \
+                          "the selected specs may not exercise them.")
+        map
+      end
+
       def died(status)
         how = if status&.signaled? then "was killed by signal #{Signal.signame(status.termsig)}"
               else "exited with status #{status&.exitstatus}"

data/lib/saboteur/engine/data_inputs.rb

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Non-Ruby files a test run can read and that change its outcome: Rails
+    # fixtures, schema dumps and database/environment configuration, plus
+    # anything listed under `fingerprint_extra`. Ruby files are tracked
+    # elsewhere; these have no .rb extension, so the Ruby walk misses them.
+    # An absent pattern simply matches nothing, so plain gems are unaffected.
+    module DataInputs
+      GLOBS = %w[
+        spec/fixtures/**/*
+        spec/**/fixtures/**/*
+        test/fixtures/**/*
+        db/structure.sql
+        db/schema.rb
+        config/database.yml
+        config/database.yml.erb
+        config/*.yml
+        config/environments/*.yml
+        config/credentials/*.yml.enc
+      ].freeze
+
+      # True when the absolute path is one of the declared inputs, whether or
+      # not the file exists yet. A run must never write there.
+      def self.match?(root, path, extra: [])
+        return false unless path.start_with?("#{root}/")
+
+        relative = path.delete_prefix("#{root}/")
+        flags = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
+        (GLOBS + extra).any? { |pattern| File.fnmatch?(pattern, relative, flags) }
+      end
+
+      # Sorted absolute paths of regular files (symlinks followed) under root.
+      def self.files(root, extra: [])
+        (GLOBS + extra).flat_map { |pattern| Dir.glob(pattern, File::FNM_DOTMATCH, base: root) }
+                       .map { |relative| File.join(root, relative) }
+                       .select { |path| File.file?(path) }.uniq.sort
+      end
+    end
+  end
+end

data/lib/saboteur/engine/diagnostics.rb

@@ -6,6 +6,26 @@ module Saboteur
     # What a run has to say besides results: warnings for the report, the
     # count of mutations dropped for not parsing, and progress marks.
     class Diagnostics
+      # See progress_heartbeat. Time-gated itself, so the supervisor can
+      # call tick on every poll.
+      class ProgressHeartbeat
+        def initialize(diagnostics, label, interval: 30)
+          @diagnostics = diagnostics
+          @label = label
+          @interval = interval
+          @started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @last_print = @started
+        end
+
+        def tick
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return if now - @last_print < @interval
+
+          @last_print = now
+          @diagnostics.inform("#{@label}: #{(now - @started).round} s elapsed")
+        end
+      end
+
       MARKS = { killed: ".", survived: "S", timeout: "T", resource_limit: "L", error: "E" }.freeze
 
       attr_reader :warnings, :invalid_mutations
@@ -28,6 +48,14 @@ module Saboteur
         @err.puts("saboteur: #{message}")
       end
 
+      # A heartbeat for a long phase: the supervisor's wait loop calls tick
+      # in the parent after the fork, so no extra thread is ever alive at
+      # fork time. Prints "<label>: N s elapsed" about every interval
+      # seconds, so a long phase does not look stuck.
+      def progress_heartbeat(label, interval: 30)
+        ProgressHeartbeat.new(self, label, interval: interval)
+      end
+
       def progress(result)
         @err.print(MARKS.fetch(result.status, "?"))
         @err.flush

data/lib/saboteur/engine/diff_scope.rb

@@ -20,6 +20,14 @@ module Saboteur
         end
       end
 
+      # The changed lines a mutant touches, sorted. A statement that spans
+      # several lines is mutated as one piece and reported at its first line,
+      # which can sit above the line that changed; this names the changed line.
+      def changed_lines_for(subject, mutation)
+        changed = @changed_lines.fetch(subject.file, Set.new)
+        mutation.edits.flat_map { |edit| edited_lines(subject, edit).to_a }.uniq.select { changed.include?(_1) }.sort
+      end
+
       private
 
       def edited_lines(subject, edit)

data/lib/saboteur/engine/run_fingerprint.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "json"
+require_relative "data_inputs"
 
 module Saboteur
   class Engine
@@ -12,7 +13,7 @@ module Saboteur
       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].freeze
-      ENTRY_KINDS = %w[ruby manifest boot hook source_plugin extra].freeze
+      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)
       Change = Data.define(:path, :reason)
@@ -178,11 +179,12 @@ module Saboteur
       end
 
       def output_overlap_issues
-        paths = required_files.map(&:first) + MANIFESTS.map { |name| File.join(@root, name) }
+        paths = required_files.map(&:first) + MANIFESTS.map { |name| File.join(@root, name) } +
+                DataInputs.files(@root, extra: @config["fingerprint_extra"])
         outputs = %w[json_report html_report].filter_map { |key| @config.fetch(key) }
                                              .map { |path| canonical_path(path) }
         issues = outputs.filter_map do |path|
-          if path.end_with?(".rb") || paths.include?(path) || File.directory?(path)
+          if path.end_with?(".rb") || paths.include?(path) || File.directory?(path) || data_input?(path)
             "output overlaps input: #{display_path(path)}"
           end
         end
@@ -192,24 +194,50 @@ module Saboteur
 
       def cache_overlap_issues(paths)
         cache = canonical_path(@config["cache_dir"])
-        protected = [@root] + %w[app lib spec].map { |name| File.join(@root, name) } + paths
-        overlaps = protected.any? do |path|
+        protected = [@root] + %w[app lib spec test/fixtures].map { |name| File.join(@root, name) } + paths
+        inside = protected.any? do |path|
           path == cache || path.start_with?("#{cache}/") || (path != @root && cache.start_with?("#{path}/"))
         end
+        overlaps = inside || data_input?(cache)
         overlaps ? ["cache directory overlaps inputs: #{display_path(cache)}"] : []
       end
 
+      # Declared fixture, schema or config input, or a path inside a fixture tree.
+      def data_input?(path)
+        DataInputs.match?(@root, path, extra: @config["fingerprint_extra"])
+      end
+
       def inventory(issues)
         paths = project_files(issues).to_h { |path| [path, "ruby"] }
         MANIFESTS.each { |name| paths[File.join(@root, name)] = "manifest" }
+        data_files(issues).each { |path| paths[path] ||= "data" }
         required = merged_required_files
         required.each { |path, (kind, _)| paths[path] = kind }
         paths.map do |path, kind|
-          needed = required.key?(path) ? required[path].last : kind != "manifest"
+          needed = required.key?(path) ? required[path].last : !%w[manifest data].include?(kind)
           read_entry(path, kind, needed, issues)
         end
       end
 
+      # Fixtures, schema dumps and database config. A pattern with no match is
+      # fine; a listed file that vanishes later shows up as "removed". Like Ruby
+      # files, data reached through a symlink (the file or a directory above it)
+      # is an undeclared boundary: its real path could be an output or lie outside
+      # the project, so the snapshot is incomplete instead of guessing.
+      def data_files(issues)
+        DataInputs.files(@root, extra: @config["fingerprint_extra"]).reject do |path|
+          next false unless symlinked?(path)
+
+          issues << "symlink input: #{display_path(path)}".freeze
+          true
+        end
+      end
+
+      def symlinked?(path)
+        current = @root
+        path.delete_prefix("#{@root}/").split("/").any? { |part| File.symlink?(current = File.join(current, part)) }
+      end
+
       def merged_required_files
         required_files.group_by(&:first).transform_values do |entries|
           roles = entries.map { |_, kind, _| kind }

data/lib/saboteur/engine/scheduler.rb

@@ -7,11 +7,10 @@ module Saboteur
     # unit of work parallel workers will share out.
     #
     # Order of business: skip what cannot be run (refinements, not loaded,
-    # shadowed, no covering test); coarse mutants; fine mutants only if no
-    # coarse mutant survived; then check every kill and timeout against the
-    # unchanged method (VerdictCheck). Each mutant runs only the tests that
-    # executed its edit, likeliest killers first, with a timeout from those
-    # tests' recorded durations.
+    # shadowed, no covering test); coarse mutants; all eligible fine mutants;
+    # then check every kill and timeout against the unchanged method
+    # (VerdictCheck). Each mutant runs only the tests that executed its edit,
+    # likeliest killers first, with a timeout from their recorded durations.
     class Scheduler
       # A subject to run, with what its mutants need. killers counts the
       # tests that killed earlier mutants of this subject; slowdown is how
@@ -45,7 +44,7 @@ module Saboteur
         reused = all_reused(plan, candidates)
         return reused if reused
 
-        results = run_candidates(plan, candidates) do |mutation, text|
+        results = run_candidates(candidates) do |mutation, text|
           reuse(plan, mutation, text) || execute(plan, mutation, text)
         end
         checked(subject, results)
@@ -86,21 +85,13 @@ module Saboteur
         return nil unless @cache
 
         catch(:must_run) do
-          run_candidates(plan, candidates) { |mutation, text| reuse(plan, mutation, text) || throw(:must_run) }
+          run_candidates(candidates) { |mutation, text| reuse(plan, mutation, text) || throw(:must_run) }
         end
       end
 
-      def run_candidates(plan, candidates, &run_one)
+      def run_candidates(candidates, &run_one)
         coarse, fine = candidates.partition { |mutation, _| mutation.coarse }
         results = coarse.map { |mutation, text| run_one.call(mutation, text) }
-        # A surviving coarse mutant means nothing checks the body, so the fine
-        # mutants would only add noise. Not so when a rescue or else can
-        # return a value of its own: fine mutants that make the body raise
-        # can still be caught.
-        if results.any?(&:survived?) && !plan.subject.recovers?
-          return results + skip_all(fine, plan.subject, "coarse mutant survived", covered_by: plan.tests)
-        end
-
         results + fine.map { |mutation, text| run_one.call(mutation, text) }
       end
 

data/lib/saboteur/engine/suite_files.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "shellwords"
+require_relative "data_inputs"
 
 module Saboteur
   class Engine
@@ -22,7 +23,7 @@ module Saboteur
       end
 
       def files
-        (shared_spec_files + boot_and_hook_files + option_files + required_by_options).uniq.sort
+        (shared_spec_files + boot_and_hook_files + option_files + required_by_options + data_files).uniq.sort
       end
 
       def digest
@@ -33,6 +34,12 @@ module Saboteur
 
       private
 
+      # Fixtures, schema dumps and database config: not Ruby, but they change
+      # what the tests see, so a stale cache must not survive an edit to them.
+      def data_files
+        DataInputs.files(@root, extra: @config["fingerprint_extra"])
+      end
+
       def shared_spec_files
         Dir.glob("spec/**/*.rb", base: @root).reject { |file| file.end_with?("_spec.rb") }
            .map { |file| File.join(@root, file) }

data/lib/saboteur/engine.rb

@@ -29,20 +29,52 @@ module Saboteur
       Boot.refuse_recursion!
       started = monotonic
       ignore_list = @replay ? IgnoreList.new([]) : IgnoreList.load(config.path("ignore_file"))
+      @diagnostics.warnings.concat(custom_map_warnings(load_custom_map))
       boot = Boot.new(config, hooks)
-      integration = boot.load_target
-      @rails = boot.rails
-      files = config.included_files
-      subjects, scope = select_subjects(files)
-      results = subjects.empty? ? [] : mutate(subjects, files, integration, scope)
-      @diagnostics.warnings.concat(ignore_list.apply(results))
-      Report.new(results: results, subjects: subjects, wall_time: monotonic - started, root: @root,
-                 invalid_mutations: @diagnostics.invalid_mutations, warnings: @diagnostics.warnings,
-                 review: !scope.nil?, seed: config["seed"], skipped_subjects: @skipped_subjects)
+      begin
+        integration = boot.load_target
+        @rails = boot.rails
+        files = config.included_files
+        subjects, scope = select_subjects(files)
+        results = subjects.empty? ? [] : mutate(subjects, files, integration, scope)
+        @diagnostics.warnings.concat(ignore_list.apply(results))
+        build_report(results, subjects, scope, started)
+      ensure
+        # The run boundary for the per-worker databases: cleanup runs however
+        # the call ends - a boot that raised partway through, a baseline or
+        # coverage failure, no subjects, no runnable work - so a host that
+        # embeds Engine and calls it repeatedly never holds copies or
+        # snapshots until process exit. cleanup_workers is idempotent; the
+        # Rails profile's at_exit handler stays as the fallback for an
+        # abrupt process exit.
+        safely_cleanup_workers(boot.rails)
+      end
+    end
+
+    # Stale entries and duplicate literals never fail a run; they warn so the
+    # map does not rot silently. doctor fails on stale keys.
+    def load_custom_map
+      @replay ? CustomMap.new([]) : CustomMap.load(config.path("custom_map"), root: config.root)
+    end
+
+    def custom_map_warnings(map)
+      path = config.path("custom_map")
+      warnings = map.stale_keys.map { |key| "stale custom map key #{key}: matches no file" }
+      return warnings unless path && File.file?(path)
+
+      warnings + map.duplicate_keys(path).map { |key| "duplicate custom map key #{key}: Ruby keeps the last" }
     end
 
     private
 
+    # The run's immutable report, built once the last result is in.
+    def build_report(results, subjects, scope, started)
+      Report.new(results: results, subjects: subjects, wall_time: monotonic - started, root: @root,
+                 invalid_mutations: @diagnostics.invalid_mutations, warnings: @diagnostics.warnings,
+                 review: !scope.nil?, seed: config["seed"], skipped_subjects: @skipped_subjects,
+                 diff_scope: scope)
+    end
+
     # The subjects to mutate and, in diff mode, the scope of changed lines.
     def select_subjects(files)
       config.unmatched_patterns.each { |pattern| @diagnostics.warn("#{pattern} matches no file") }
@@ -55,6 +87,7 @@ module Saboteur
     end
 
     def mutate(subjects, files, integration, scope)
+      warn_about_unscoped_suite(integration)
       check_baseline(integration)
       map = CoverageStore.new(config: config, integration: integration, hooks: hooks,
                               supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics).fetch(files)
@@ -72,7 +105,8 @@ module Saboteur
       # are retained, to reduce later copying of shared pages.
       Execution::ForkReadiness.prepare_heap
       results = Distribution.new(jobs: config["jobs"], scheduler: scheduler, diagnostics: @diagnostics,
-                                 cache: cache, on_start: method(:start_worker)).run(runnable_subjects, runnable_lists)
+                                 cache: cache, on_start: method(:start_worker)).run(runnable_subjects,
+                                                                                    runnable_lists)
       cache&.save
       results
     end
@@ -82,6 +116,18 @@ module Saboteur
       warn_about_threads
     end
 
+    # A --since run without --test runs the loaded suite twice for the
+    # baselines; a cold coverage cache adds one more pass. Say so
+    # before those hours pass, with the way to scope it.
+    def warn_about_unscoped_suite(integration)
+      return unless config["since"] && config["tests"].empty?
+
+      message = "running the loaded suite unscoped: two baseline passes; coverage may add a pass " \
+                "(#{integration.test_files.size} spec files). Pass --test to scope it."
+      @diagnostics.warn(message)
+      @diagnostics.inform(message)
+    end
+
     def check_baseline(integration)
       BaselineGuard.new(config: config, integration: integration, hooks: hooks,
                         supervisor: supervisor(memory_factor: 4), diagnostics: @diagnostics).call
@@ -104,6 +150,14 @@ module Saboteur
                       suite_digest: SuiteFiles.new(config).digest)
     end
 
+    # A cleanup failure must never mask the run's own outcome - not even
+    # one cleanup_workers did not anticipate.
+    def safely_cleanup_workers(rails)
+      rails&.cleanup_workers
+    rescue StandardError => e
+      @diagnostics.warn(e.message)
+    end
+
     # In each worker: its own database, then the user's worker_start hooks.
     def start_worker(number)
       @rails&.start_worker(number)
@@ -143,10 +197,17 @@ module Saboteur
       end
     end
 
+    # Threads do not survive fork, so name them: with the name the owner
+    # gave the thread, else the first frame of its backtrace, so the user
+    # can tell whether they matter (a connection pool reaper, Sidekiq, an
+    # SDK's background flusher).
     def warn_about_threads
-      others = Thread.list.size - 1
-      @diagnostics.warn("#{others} other thread(s) alive at fork time; they do not run in children") if
-        others.positive?
+      others = Thread.list - [Thread.current]
+      return if others.empty?
+
+      names = others.map { |thread| thread.name || thread.backtrace&.first || "unknown" }
+      list = names.join(", ")
+      @diagnostics.warn("#{others.size} other thread(s) alive at fork time; they do not run in children: #{list}")
     end
 
     def monotonic

data/lib/saboteur/execution/reevaluator.rb

@@ -29,11 +29,12 @@ module Saboteur
         target = subject.singleton ? owner.singleton_class : owner
         visibility = visibility_of(target, subject.name)
         module_function = module_function?(owner, subject)
+        copy_visibility = visibility_of(owner.singleton_class, subject.name) if module_function
         aliases = aliases_of(target, subject.name)
 
         @strategy == "nesting" ? eval_nested(subject, text) : eval_in_owner(owner, subject, text)
 
-        restore(owner, target, subject.name, visibility, module_function)
+        restore(owner, target, subject.name, visibility, copy_visibility)
         repoint(target, subject.name, aliases)
       end
 
@@ -82,7 +83,8 @@ module Saboteur
       def module_function?(owner, subject)
         return false if subject.singleton || owner.is_a?(Class)
         return false unless owner.private_method_defined?(subject.name, false)
-        return false unless owner.singleton_class.public_method_defined?(subject.name, false)
+        return false unless owner.singleton_class.method_defined?(subject.name, false) ||
+                            owner.singleton_class.private_method_defined?(subject.name, false)
 
         owner.instance_method(subject.name).source_location ==
           owner.singleton_class.instance_method(subject.name).source_location
@@ -132,9 +134,10 @@ module Saboteur
         end
       end
 
-      def restore(owner, target, name, visibility, module_function)
-        if module_function
+      def restore(owner, target, name, visibility, copy_visibility)
+        if copy_visibility
           owner.send(:module_function, name)
+          owner.singleton_class.send(copy_visibility, name)
         elsif visibility != :public
           target.send(visibility, name)
         end

data/lib/saboteur/execution/supervisor.rb

@@ -94,7 +94,10 @@ module Saboteur
       # Runs the block in a forked child with a pipe writer; the child exits
       # when the block returns. Returns a Result. cpu_seconds bounds every
       # descendant's CPU time (default: twice the deadline, at least 10 s).
-      def run(timeout:, cpu_seconds: nil, &block)
+      # on_tick is called from the parent's wait loop after the fork, about
+      # every poll, so callers can report progress without a thread alive
+      # at fork time.
+      def run(timeout:, cpu_seconds: nil, on_tick: nil, &block)
         depth = ENV.fetch(CHILD_ENV, "0").to_i
         raise Error, "refusing to fork: saboteur children nested #{depth} deep (limit #{MAX_DEPTH})" if
           depth >= MAX_DEPTH
@@ -107,7 +110,7 @@ module Saboteur
         supervisor = Process.pid
         pid = fork { child(reader, writer, supervisor, cpu_seconds, depth + 1, &block) }
         writer.close
-        contain(pid, reader, started, timeout)
+        contain(pid, reader, started, timeout, on_tick)
       ensure
         reader&.close unless reader&.closed?
       end
@@ -168,24 +171,31 @@ module Saboteur
 
       # --- parent ---------------------------------------------------------
 
-      def contain(pid, reader, started, timeout)
+      def contain(pid, reader, started, timeout, on_tick)
         tree = ProcessTree.new(pid)
         self.class.live[pid] = tree
         own_group(pid)
-        payload, stop, detail = watch(tree, reader, started + timeout)
-        exit_status = stop == :timeout ? terminate(pid) : nil
-        leftover_pids = tree.kill_all - [pid]
-        exit_status ||= reap(pid)
-        self.class.live.delete(pid)
-        reap_adopted(leftover_pids)
-        reap_group(pid)
+        begin
+          payload, stop, detail = watch(tree, reader, started + timeout, on_tick)
+        ensure
+          # Containment holds on every path out of watch: a raising on_tick
+          # (progress IO failed) or any other error must not skip the
+          # kill/reap, or the child and its tree would run unsupervised
+          # until this process exits.
+          exit_status = stop == :timeout ? terminate(pid) : nil
+          leftover_pids = tree.kill_all - [pid]
+          exit_status ||= reap(pid)
+          self.class.live.delete(pid)
+          reap_adopted(leftover_pids)
+          reap_group(pid)
+        end
         Result.new(payload: payload, exit_status: exit_status, stopped_by: stop, detail: detail,
                    runtime: monotonic - started, leftover_pids: leftover_pids)
       end
 
       # Reads until EOF, polling the tree's size and memory. Returns
       # [payload, stop, detail].
-      def watch(tree, reader, deadline)
+      def watch(tree, reader, deadline, on_tick)
         payload = +""
         next_poll = monotonic + POLL_INTERVAL
         tree.live_members
@@ -193,6 +203,8 @@ module Saboteur
           now = monotonic
           return [payload, :timeout, "exceeded deadline"] if now >= deadline
 
+          on_tick&.call
+
           if now >= next_poll
             stop = over_limit(tree)
             return [payload, *stop] if stop