henitai 0.1.10 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a993f2073367de6b25c8fe922a2089f57103d79790c1e9cd95d2ba6b573b3050
-  data.tar.gz: d6956c7b23f1ec7cd97773cdd249a2c12b17f75e080cb98092d34049a763c607
+  metadata.gz: b2062372801be4391691c6040c2221147a5b14ec346726466d1abe8e916a7670
+  data.tar.gz: b51bd86b3f98751b4cc28bf0e443c56158fe6051f754e2ed954dc74940824f29
 SHA512:
-  metadata.gz: e7a1925ad77b77ac4ed802b3419b15988a436098488a2dfb0ee11f8f930da024bc05a686606ae4e86ba6fd9f36ef4aed19ef8b1e46bef31e143d25ee4dc54ded
-  data.tar.gz: f095d945bd5f9313a202db7a6ce3936a69233b47d62b92ec353950857c27d58b75dc8084164383d66558ef2a076c62e2fd53e68621d8b9d95546c6b1114faa73
+  metadata.gz: d128d68a96d10a3aeccdd88654cce9ef2ad53d527f196c1a29c1f02416f7d1b045989766872eef92b1832f8a283fdc726fc3b994098b464b22d91897a2993450
+  data.tar.gz: 9b13d2a228c4fd266b49db1d102ca796cd71c534458a341565fd2c1788088bd33f22c1c32bd5c9eeaee4f72d6c3658ea431a78eb5631960299736aea9575b627

data/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-30
+
+### Added
+- `--survivors-from <path>` flag on `henitai run` for survivor-only reruns:
+  re-execute only the mutants that survived a prior full run without re-running
+  the whole suite
+- `SurvivorLoader` reads a Stryker-compatible JSON report and extracts survivor
+  IDs, per-survivor coverage maps (`coveredBy`), and the anchoring git SHA
+- `SurvivorSelector` filters the current mutant set to the survivor subset; emits
+  a drift warning when more than 50% of loaded survivors are unmatched (source
+  changed significantly since the prior run)
+- `SurvivorTestFilter` skips survivors whose covering tests are unchanged since
+  the prior report's git SHA, marking them `:survived` immediately without
+  execution — same safety logic as StrykerJS incremental mode
+- `MutantIdentity` module: stable SHA256 identity computed from expression,
+  operator, description, location, and mutation signature; shared by
+  `MutantHistoryStore` and `Mutant#stable_id`
+- `Mutant#stable_id` exposes the stable identity; emitted as `stableId` in the
+  JSON report so survivor reports remain useful across commits
+- `Result` carries `session_id` (UUID) and optional `git_sha` (HEAD SHA at
+  report time); both emitted in the Stryker-compatible JSON as `sessionId` /
+  `gitSha`
+- `Reporter::Json` writes an immutable per-session snapshot alongside the
+  canonical report at `reports/sessions/<session_id>/mutation-report.json`,
+  giving `--survivors-from` a stable reference path across runs
+- `GitDiffAnalyzer#head_sha` — returns the current HEAD SHA; `nil` when git is
+  unavailable (conservative fallback: all survivors are executed)
+- `ProcessWorkerRunner` — flat process-slot scheduler for parallel mutant
+  execution: each slot owns one OS process, slots are refilled as children
+  finish, no thread per child
+- Interrupt handling, spawn failure isolation, and in-slot retry added to
+  `ProcessWorkerRunner` (PR 6)
+- Timeout precision and two-phase process-group cleanup in
+  `ProcessWorkerRunner` (PR 5)
+- x86_64 platform added to gem platform list
+
+### Changed
+- JSON mutation report vendor extension now always includes `sessionId`
+  (and `gitSha` when available) to support survivor-only reruns
+- Terminal reporter labels partial reruns as "Partial survivor rerun" and
+  shows matched / unmatched / skipped-by-diff counts
+- History store skips `runs` row insertion for partial reruns to avoid
+  distorting trend analytics; per-mutant `current_status` upsert still runs
+- CLI exits 0 for partial reruns with a printed warning; threshold comparison
+  is skipped (applying a partial score to a CI gate is misleading)
+- `StaticFilter` merges per-test coverage into standard coverage so
+  `coveredBy` data is available to both RSpec and Minitest survivor reports
+- `.henitai.yml` default: operators set to `light`, timeout lowered to 10 s,
+  `max_flaky_retries: 3` added
+
+### Fixed
+- Minitest autorun hook suppressed in mutation child processes to prevent
+  spurious re-runs of the full suite inside each fork
+- Coverage bootstrap RSpec subprocess ARGV leakage resolved — child processes
+  no longer inherit the parent's `--format` / file arguments
+- Survivor rerun state preserved across RSpec execution (was reset on each
+  subprocess boot)
+- `--survivors-from` now respects dirty worktrees: coverage and source file
+  state are read from the working tree, not the index
+- Recipe fast path skipped when source files changed since the cached run,
+  preventing stale cache hits after edits
+
+### Performance
+- File discovery cached in the integration layer; repeated calls within one
+  run no longer re-scan the filesystem
+- Polling sleep removed from the scheduler hot loop; slots are refilled
+  event-driven on child exit
+
 ## [0.1.10] - 2026-04-16
 
 ### Fixed

data/README.md

@@ -15,10 +15,9 @@ A Ruby mutation testing framework
 ## Maturaty
 
 - This is alpha software, there will be bugs
-- Henitai tests itself
-- Stryker Dashboard support is untested
-- Minitest support is untested
-- Lots of code has been carefully crafted by AI agents, not everything has been reviewed by humans (yet)
+- Henitai tests itself and other projects
+- It might break with a release
+- If you need a mature solution for mutation testing in ruby, take a look at the [https://github.com/mbj/mutant](Mutant gem)
 
 ## What is mutation testing?
 
@@ -28,6 +27,8 @@ A mutation testing tool makes small, systematic changes — *mutants* — to you
 
 The ratio of killed mutants to total mutants is the **Mutation Score** (MS). A high mutation score is a strong quality signal.
 
+As mutation testing modifies your code you make sure that your tests cannot have any unintended side-effects.
+
 ## Installation
 
 Add to your `Gemfile`:
@@ -56,6 +57,9 @@ bundle exec henitai run --since origin/main
 # Run on a specific subject pattern
 bundle exec henitai run 'MyClass#my_method'
 bundle exec henitai run 'MyNamespace*'
+
+# Re-run only survivors from a prior mutation report
+bundle exec henitai run --survivors-from reports/mutation-report.json
 ```
 
 Configuration lives in `.henitai.yml`:
@@ -112,6 +116,12 @@ and the terminal only shows progress plus a concise summary. Pass
 when the mutation score meets the low threshold, `1` when it does not, and `2`
 for framework errors.
 
+`henitai run --survivors-from ...` performs a partial rerun: it reports only
+the selected survivors, skips threshold-based exit checks, and does not update
+the run trend history. Dirty worktree changes are included, so you can edit
+tests locally without committing first; if source files under `includes` are
+dirty, Henitai reruns the matched survivors conservatively.
+
 The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/workspaces/henitai/assets/schema/henitai.schema.json) for editor autocompletion.
 
 ## Operator sets
@@ -172,6 +182,10 @@ Framework integration smoke projects live under `spec/fixtures/integration_smoke
 and exercise `henitai` against small RSpec and Minitest apps via the local path
 dependency.
 
+Git hook support is tracked in [`.githooks/pre-commit`](/Users/martinotten/projects/mo/henitai/.githooks/pre-commit).
+Enable it with `git config core.hooksPath .githooks` so commits run RuboCop,
+RSpec, and the integration smoke suite before they are created.
+
 A Dev Container configuration is included (`.devcontainer/`) for VS Code with the official `ruby:4`
 image, the Codex CLI, and RTK preinstalled. Codex support is bootstrapped with
 `rtk init -g --codex --auto-patch` during container creation.

data/lib/henitai/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
 require "optparse"
 module Henitai
   # Command-line interface entry point.
@@ -100,7 +101,7 @@ module Henitai
 
       config = load_config(options)
       result = run_pipeline(options, config)
-      exit(exit_status_for(result, config))
+      exit(exit_status_for(result, config, fail_on_survivors: options[:fail_on_survivors]))
     rescue StandardError => e
       handle_run_error(e)
     end
@@ -160,6 +161,8 @@ module Henitai
         add_operator_option(opts, options)
         add_jobs_option(opts, options)
         add_output_option(opts, options)
+        add_survivors_from_option(opts, options)
+        add_fail_on_survivors_option(opts, options)
         add_help_option(opts)
         add_version_option(opts)
       end
@@ -216,6 +219,25 @@ module Henitai
       end
     end
 
+    def add_survivors_from_option(opts, options)
+      opts.on(
+        "--survivors-from PATH",
+        "Re-run only survivors from a prior report " \
+        "(partial rerun; threshold checks are skipped; dirty worktrees are included)"
+      ) do |path|
+        options[:survivors_from] = path
+      end
+    end
+
+    def add_fail_on_survivors_option(opts, options)
+      opts.on(
+        "--fail-on-survivors",
+        "Exit 1 for partial reruns when any survivors remain (otherwise exits 0)"
+      ) do
+        options[:fail_on_survivors] = true
+      end
+    end
+
     def add_help_option(opts)
       opts.on("-h", "--help", "Show this help") do
         puts opts
@@ -246,6 +268,7 @@ module Henitai
           bundle exec henitai run --since origin/main
           bundle exec henitai run 'Foo::Bar#my_method'
           bundle exec henitai run 'MyNamespace*' --operators full
+          bundle exec henitai run --survivors-from reports/mutation-report.json
           bundle exec henitai clean
           bundle exec henitai init
           bundle exec henitai operator list
@@ -255,14 +278,55 @@ module Henitai
     end
 
     def run_pipeline(options, config)
+      resolved_survivors_from = resolve_survivors_from(options[:survivors_from])
       runner = Runner.new(
         config:,
         subjects: subjects_from_argv,
-        since: options[:since]
+        since: options[:since],
+        survivors_from: resolved_survivors_from
       )
       runner.run
     end
 
+    def resolve_survivors_from(survivors_from)
+      return nil if survivors_from.nil?
+
+      # Fast path: if the path already points into reports/sessions/<session_id>/,
+      # keep it as-is so activation-recipes.json can be found by the runner.
+      report_dir = File.dirname(survivors_from)
+      parent_dir = File.dirname(report_dir)
+      # Heuristic: treat any path under a directory named "sessions" as already
+      # being a snapshot path; this keeps activation-recipes lookup correct.
+      return survivors_from if File.basename(parent_dir) == "sessions"
+
+      session_id = session_id_from_report(survivors_from)
+      return survivors_from if session_id.nil?
+
+      snapshot_path = survivors_snapshot_path(report_dir, session_id)
+      recipe_path = File.join(report_dir, "sessions", session_id, "activation-recipes.json")
+      return snapshot_path if File.exist?(recipe_path) && File.exist?(snapshot_path)
+
+      # If the recipes exist but the snapshot doesn't (e.g. partial cleanup),
+      # fall back to the path the user provided so the error message points
+      # at what they actually passed.
+
+      survivors_from
+    rescue StandardError => e
+      warn_survivors_from_resolution_error(survivors_from, e)
+      survivors_from
+    end
+
+    def survivors_snapshot_path(report_dir, session_id)
+      File.join(report_dir, "sessions", session_id, "mutation-report.json")
+    end
+
+    def session_id_from_report(path)
+      parsed = JSON.parse(File.read(path))
+      parsed["sessionId"]
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
     def load_config(options)
       Configuration.load(
         path: options.fetch(:config, Configuration::CONFIG_FILE),
@@ -279,6 +343,13 @@ module Henitai
       exit 2
     end
 
+    def warn_survivors_from_resolution_error(survivors_from, error)
+      warn(
+        "henitai: warning: could not resolve survivors-from " \
+        "#{survivors_from}: #{error.class}: #{error.message}"
+      )
+    end
+
     def clean_summary(removed_paths)
       return "No generated report artifacts to clean" if removed_paths.empty?
 
@@ -301,7 +372,14 @@ module Henitai
       end
     end
 
-    def exit_status_for(result, config)
+    def exit_status_for(result, config, fail_on_survivors: false)
+      if result.respond_to?(:partial_rerun?) && result.partial_rerun?
+        warn "henitai: partial rerun - mutation score threshold not evaluated"
+        return result.survived.positive? ? 1 : 0 if fail_on_survivors
+
+        return 0
+      end
+
       result.mutation_score.to_i >= config.thresholds.fetch(:low, 60) ? 0 : 1
     end
 

data/lib/henitai/configuration.rb

@@ -35,6 +35,7 @@ module Henitai
     end
 
     def initialize(path: CONFIG_FILE, overrides: {})
+      @config_dir = File.dirname(File.expand_path(path))
       raw = load_raw_configuration(path)
       unless raw.is_a?(Hash)
         raise Henitai::ConfigurationError,
@@ -54,6 +55,14 @@ module Henitai
       raw || {}
     end
 
+    def detect_integration
+      return "rspec"    if File.exist?(File.join(@config_dir, ".rspec"))
+      return "minitest" if File.directory?(File.join(@config_dir, "test"))
+      return "rspec"    if File.directory?(File.join(@config_dir, "spec"))
+
+      "rspec"
+    end
+
     def apply_defaults(raw)
       apply_general_defaults(raw)
       apply_mutation_defaults(raw)
@@ -61,22 +70,13 @@ module Henitai
     end
 
     def apply_general_defaults(raw)
-      integration = raw[:integration]
-      @integration = if integration.is_a?(Hash)
-                       integration[:name] || "rspec"
-                     elsif integration.nil?
-                       "rspec"
-                     else
-                       integration
-                     end
+      @integration = resolve_integration_default(raw[:integration])
       @includes = raw[:includes] || ["lib"]
       @jobs = raw.fetch(:jobs, DEFAULT_JOBS)
       @reporters = raw[:reporters] || ["terminal"]
       @reports_dir = raw[:reports_dir] || DEFAULT_REPORTS_DIR
       @all_logs = raw[:all_logs] == true
-      # @type var empty_dashboard: Hash[Symbol, untyped]
-      empty_dashboard = {}
-      @dashboard = merge_defaults(empty_dashboard, raw[:dashboard])
+      @dashboard = default_dashboard(raw[:dashboard])
     end
 
     def apply_mutation_defaults(raw)
@@ -111,6 +111,19 @@ module Henitai
       end
     end
 
+    def resolve_integration_default(integration)
+      return integration[:name] || detect_integration if integration.is_a?(Hash)
+      return detect_integration if integration.nil?
+
+      integration
+    end
+
+    def default_dashboard(overrides)
+      # @type var empty_dashboard: Hash[Symbol, untyped]
+      empty_dashboard = {}
+      merge_defaults(empty_dashboard, overrides)
+    end
+
     def symbolize_keys(value)
       case value
       when Hash

data/lib/henitai/coverage_bootstrapper.rb

@@ -18,16 +18,18 @@ module Henitai
     def ensure!(source_files:, config:, integration:, test_files: nil)
       return if source_files.empty?
 
+      resolved_test_files = resolve_test_files(integration, test_files)
+
       # Skip the bootstrap only when the coverage artifacts are both newer than
       # all watched files and actually cover the configured sources. A fresh
       # but irrelevant report (e.g. from a different working directory) must
       # still trigger a re-bootstrap rather than silently proceeding with no
       # usable coverage.
-      unless coverage_ready?(source_files, config, integration, test_files)
-        bootstrap_coverage(integration, config, test_files)
+      unless coverage_ready?(source_files, config, integration, resolved_test_files)
+        bootstrap_coverage(integration, config, resolved_test_files)
       end
 
-      return if coverage_available?(source_files, config, test_files)
+      return if coverage_available?(source_files, config)
 
       raise CoverageError,
             "Coverage data is unavailable for the configured source files"
@@ -37,20 +39,16 @@ module Henitai
 
     attr_reader :static_filter
 
-    def coverage_available?(source_files, config, test_files)
+    def coverage_available?(source_files, config)
       coverage_lines = static_filter.coverage_lines_for(config)
       covered_sources = covered_source_files(source_files, coverage_lines)
-      existing_sources = existing_source_file_paths(source_files)
-
-      return covered_sources.any? if existing_sources.empty?
-      return covered_sources.any? if test_files
 
       covered_sources.any?
     end
 
     def coverage_ready?(source_files, config, integration, test_files)
-      coverage_fresh?(source_files, config, integration, test_files) &&
-        coverage_available?(source_files, config, test_files) &&
+      coverage_fresh?(source_files, config, test_files) &&
+        coverage_available?(source_files, config) &&
         per_test_coverage_ready?(source_files, config, integration, test_files)
     end
 
@@ -64,17 +62,12 @@ module Henitai
       Array(source_files).map { |path| File.expand_path(path) }
     end
 
-    def existing_source_file_paths(source_files)
-      source_file_paths(source_files).select { |path| File.exist?(path) }
-    end
-
     # Returns true when a coverage report already exists and is newer than
     # every watched source and test file. Stale or absent reports return false.
-    def coverage_fresh?(source_files, config, integration, test_files)
+    def coverage_fresh?(source_files, config, test_files)
       watched_files_fresh?(
         coverage_report_path(config),
         source_files,
-        integration,
         test_files
       )
     end
@@ -88,9 +81,11 @@ module Henitai
     end
 
     def bootstrap_coverage(integration, config, test_files = nil)
+      test_files ||= integration.test_files
+
       with_reports_dir(config) do
         with_coverage_dir(config) do
-          result = integration.run_suite(test_files || integration.test_files)
+          result = integration.run_suite(test_files)
           return if result == :survived
 
           raise CoverageError, build_bootstrap_error(result)
@@ -139,11 +134,10 @@ module Henitai
       File.join(reports_dir, "coverage")
     end
 
-    def per_test_coverage_fresh?(source_files, config, integration, test_files)
+    def per_test_coverage_fresh?(source_files, config, test_files)
       watched_files_fresh?(
         per_test_coverage_report_path(config),
         source_files,
-        integration,
         test_files
       )
     end
@@ -155,7 +149,7 @@ module Henitai
     def per_test_coverage_ready?(source_files, config, integration, test_files)
       return true unless per_test_coverage_supported?(integration)
 
-      per_test_coverage_fresh?(source_files, config, integration, test_files) &&
+      per_test_coverage_fresh?(source_files, config, test_files) &&
         per_test_coverage_available?(config)
     end
 
@@ -165,21 +159,27 @@ module Henitai
       integration.per_test_coverage_supported?
     end
 
-    def watched_files_fresh?(report_path, source_files, integration, test_files)
+    def watched_files_fresh?(report_path, source_files, test_files)
       # This check assumes a single writer owns the coverage artifacts for the
       # workspace. It is intentionally not an atomic snapshot-and-validate step.
       return false unless File.exist?(report_path)
 
       report_mtime = File.mtime(report_path)
-      watched_files(source_files, integration, test_files).all? do |path|
+      watched_files(source_files, test_files).all? do |path|
         File.mtime(path) <= report_mtime
       rescue Errno::ENOENT
         false
       end
     end
 
-    def watched_files(source_files, integration, test_files)
-      Array(source_files) + Array(test_files || integration.test_files)
+    def watched_files(source_files, test_files)
+      Array(source_files) + Array(test_files)
+    end
+
+    def resolve_test_files(integration, test_files)
+      return test_files unless test_files.nil?
+
+      integration.test_files
     end
 
     def reports_dir(config)

data/lib/henitai/execution_engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "parallel_execution_runner"
+require_relative "process_worker_runner"
 
 module Henitai
   # Runs pending mutants through the selected integration.
@@ -46,24 +47,17 @@ module Henitai
     end
 
     def run_parallel(mutants, integration, config, progress_reporter)
-      ParallelExecutionRunner.new(
+      ProcessWorkerRunner.new(
         worker_count: worker_count(config)
       ).run(
         mutants,
         integration,
         config,
         progress_reporter,
-        stdin_pipe: pipe_stdin?,
-        process_mutant: method(:process_mutant)
+        test_file_resolver: ->(mutant) { prioritized_tests_for(mutant, integration, config) }
       )
     end
 
-    def pipe_stdin?
-      $stdin.stat.pipe?
-    rescue Errno::EBADF
-      false
-    end
-
     def process_mutant(mutant, integration, config, progress_reporter, mutex)
       test_files = prioritized_tests_for(mutant, integration, config)
       mutant.covered_by = test_files if mutant.respond_to?(:covered_by=)

data/lib/henitai/git_diff_analyzer.rb

@@ -19,6 +19,21 @@ module Henitai
       stdout.split("\n").reject(&:empty?)
     end
 
+    def working_tree_changed_files(dir: Dir.pwd)
+      tracked = working_tree_tracked_files(dir)
+      untracked = untracked_files(dir)
+
+      (tracked + untracked).uniq
+    end
+
+    def head_sha(dir: Dir.pwd)
+      command = ["git", "-C", dir, "rev-parse", "HEAD"]
+      stdout, _, status = Open3.capture3(*command)
+      stdout.strip if status.success? && !stdout.strip.empty?
+    rescue Errno::ENOENT
+      nil
+    end
+
     def changed_methods(from:, to:, dir: Dir.pwd)
       changed_files(from:, to:, dir:).flat_map do |path|
         changed_methods_in_file(path, from:, to:, dir:)
@@ -78,5 +93,24 @@ module Henitai
 
       Open3.capture3(*command)
     end
+
+    def working_tree_tracked_files(dir)
+      stdout, stderr, status = git_diff(dir, "--name-only", "HEAD")
+
+      raise GitDiffError, stderr.strip unless status.success?
+
+      stdout.split("\n").reject(&:empty?)
+    end
+
+    def untracked_files(dir)
+      command = ["git"]
+      command += ["-C", dir] if dir
+      command += ["ls-files", "--others", "--exclude-standard"]
+      stdout, stderr, status = Open3.capture3(*command)
+
+      raise GitDiffError, stderr.strip unless status.success?
+
+      stdout.split("\n").reject(&:empty?)
+    end
   end
 end

data/lib/henitai/integration/rspec_process_runner.rb

@@ -2,15 +2,68 @@
 
 module Henitai
   module Integration
+    # Tracks real OS child pids for scheduler observability.
+    # Gated on HENITAI_DEBUG_SCHEDULER=1. Thread-safe.
+    module SchedulerDiagnostics
+      @mutex = Mutex.new
+      @intervals = []
+      @live_count = 0
+      @max_concurrent = 0
+
+      class << self
+        def enabled?
+          ENV["HENITAI_DEBUG_SCHEDULER"] == "1"
+        end
+
+        def child_started(pid)
+          return unless enabled?
+
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @mutex.synchronize do
+            @live_count += 1
+            @max_concurrent = [@max_concurrent, @live_count].max
+            @intervals << { pid: pid, started_at: started_at, ended_at: nil }
+          end
+        end
+
+        def child_ended(pid)
+          return if pid.nil? || !enabled?
+
+          ended_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @mutex.synchronize do
+            @live_count -= 1
+            entry = @intervals.rfind { |i| i[:pid] == pid && i[:ended_at].nil? }
+            entry[:ended_at] = ended_at if entry
+          end
+        end
+
+        def summary
+          @mutex.synchronize { { max_concurrent: @max_concurrent, intervals: @intervals.dup } }
+        end
+
+        def reset!
+          @mutex.synchronize do
+            @intervals = []
+            @live_count = 0
+            @max_concurrent = 0
+          end
+        end
+      end
+    end
+
+    # Captures the PID and log paths for a spawned mutant child process.
+    ChildHandle = Struct.new(:pid, :log_paths)
+
     # Runs RSpec child and suite processes on behalf of the integration.
     class RspecProcessRunner
       def run_mutant(integration, mutant:, test_files:, timeout:)
-        log_paths = integration.scenario_log_paths(mutant_log_name(mutant))
-        pid = fork_mutant_process(integration, mutant, test_files, log_paths)
-        wait_result = integration.wait_with_timeout(pid, timeout)
-        integration.build_result(wait_result, log_paths)
+        handle = integration.spawn_mutant(mutant:, test_files:)
+        SchedulerDiagnostics.child_started(handle.pid)
+        wait_result = integration.wait_with_timeout(handle.pid, timeout)
+        integration.build_result(wait_result, handle.log_paths)
       ensure
-        finalize_mutant_run(integration, pid, wait_result)
+        SchedulerDiagnostics.child_ended(handle&.pid)
+        finalize_mutant_run(integration, handle&.pid, wait_result)
       end
 
       def run_suite(integration, test_files, timeout:)
@@ -27,10 +80,11 @@ module Henitai
         end
       end
 
-      private
-
-      def fork_mutant_process(integration, mutant, test_files, log_paths)
-        Process.fork do
+      # Called from Integration::Rspec#spawn_mutant (and Minitest#spawn_mutant).
+      # Forks a child, sets process group, activates the mutant, runs tests.
+      # Returns a ChildHandle with the forked pid and log_paths.
+      def spawn_mutant(integration, mutant:, test_files:, log_paths:)
+        pid = Process.fork do
           Process.setpgid(0, 0)
           ENV["HENITAI_MUTANT_ID"] = mutant.id
           Process.exit(
@@ -41,18 +95,17 @@ module Henitai
             )
           )
         end
+        ChildHandle.new(pid:, log_paths:)
       end
 
+      private
+
       def finalize_mutant_run(integration, pid, wait_result)
         return unless pid
 
         integration.cleanup_process_group(pid) unless wait_result == :timeout
         integration.reap_child(pid) if wait_result.nil?
       end
-
-      def mutant_log_name(mutant)
-        "mutant-#{mutant.id}"
-      end
     end
   end
 end