henitai 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 458245aa72b025224bd6c95c2bcca98ea095dd86a41e93ab8f0671ba56644369
-  data.tar.gz: 94a822238b18f41803753a85adae77675f422d2a901cdd89723ea68b14a8842a
+  metadata.gz: 34e96b6bb2bd74ac49e52a2acbe459ccb551498914d8b442f56c427c8b8ef45c
+  data.tar.gz: 2792932da92f73f6e4cfcc0a67aa28dca405fd4cee6d02437e13f76fbd9ee08d
 SHA512:
-  metadata.gz: ed70e5425023aa08cd3ecd4ff6cb20dbd6c78b14f1811caaf9b43034e7649cdfeed617398a4fbf200730c1f4e8a36ab1fdfbe727b27379f4ed3b4eeef53be781
-  data.tar.gz: 0f2b4a04643f9e1bcd3f188e06d851f34eafbbf65dcafd42b9698678cb0ee540fca70e31207003d81cb4713ee1ca2c78901780e5f474128e20331c150949052a
+  metadata.gz: 5fe64e42c96aaa19d26bdf1a45631146bea7cb6d8caca5891d75ac6da0bdb3c30843ea8a83e34a67d0f90559fe41229d46a7000478cdd3708fb7929efea9f209
+  data.tar.gz: 39432815b88d834f6eb30be76255240b8124339505a86d8f644f2cd48ad787d85c6eb9ea9e7a85191262540e06ac467a9c32ad326a306e10953d9e758355d7bf

data/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-21
+
+### Security
+- `sqlite3` requirement raised from `~> 1.7` to `>= 2.9.5, < 3`, excluding the
+  vulnerable releases up to and including 2.9.4. This is a runtime major bump:
+  applications pinned to `sqlite3` 1.x will need to upgrade before installing
+  this version of henitai. The root bundle also moves to `json` 2.21.2, the
+  patched release. `spec/infra/gemspec_dependencies_spec.rb` now asserts both
+  floors so a regression fails the suite rather than shipping quietly
+
+### Changed
+- `coverage_criteria` now actually affects scoring. The block was documented,
+  defaulted and validated since it was introduced, but nothing ever read it —
+  `Result` hardcoded the `MS` numerator as `killed + timeout + runtime_error`,
+  so flipping `coverage_criteria.timeout` silently did nothing. It is now
+  consumed by `Result`, mapping `test_result` to `Killed`, `timeout` to
+  `Timeout` and `process_abort` to `RuntimeError`.
+
+  The shipped defaults for `timeout` and `process_abort` were `false`, which
+  described behavior the scorer did not have. They are now `true`, so **scores
+  do not move**: wiring the knob up with the old defaults intact would have
+  dropped timeouts and process aborts out of every user's numerator. Turning a
+  criterion off removes that status from the numerator only — the denominator is
+  unaffected, and `MSI` remains `killed / total` by definition. Note that
+  turning one off can move a run across its threshold and so change the exit
+  code
+- Minimum supported Ruby lowered from 4.0.0 to 3.3.6, making henitai usable by
+  projects not yet on Ruby 4. The only Ruby 4-only API in use was
+  `Enumerable#rfind`, replaced by `reverse_each.find`; `TargetRubyVersion` is
+  now `3.3` (a 4.0 target made RuboCop's `Style/ReverseFind` demand the
+  4.0-only form), and CI runs the floor alongside 4.0.2
+
+### Fixed
+- Forked mutant children no longer outlive a parent that dies without warning.
+  Children run in their own process group, and all parent-side cleanup —
+  timeout kills, graceful drain, signal traps — only runs while the parent's
+  event loop is alive, so a `kill -9`, an OOM kill or a crash left children
+  running with no signal delivered: they reparented to init and each kept a
+  full Ruby and test-framework image resident (runs were observed leaving a
+  dozen behind, several gigabytes in total). Each child now starts a watchdog
+  that exits once its parent is gone. Set `HENITAI_CHILD_WATCHDOG=0` to
+  disable it, or `HENITAI_CHILD_WATCHDOG_INTERVAL` to change the poll interval
+  (default `1.5` seconds)
+- The orphan watchdog no longer mistakes a live parent for a dead one when the
+  project's own suite stubs `Process.kill` or `Process.ppid`. Both primitives
+  are now captured as `Method` objects at load time, before any test double can
+  replace them — a captured `Method` keeps pointing at the original definition
+  even after the singleton method is redefined. This was not hypothetical: on
+  henitai's own dogfood run a mutant child running specs that stub
+  `Process.kill` to raise `ESRCH` concluded it had been orphaned and exited,
+  which the scheduler recorded as `CompileError`. Fixing it turned two spurious
+  `CompileError`s and one spurious `Timeout` back into `Killed` on a
+  1019-mutant run
+- A surviving child could also pin the reports-directory lock open, because
+  `flock` is held on the open file description that parent and child share.
+  Once the parent died, every later run in that directory failed with
+  `ConcurrentRunError` naming a pid that no longer existed. Children now close
+  the inherited handle immediately after forking
+- `# henitai:disable HashKeyType` and `# henitai:disable
+  EqualityIdentityOperator` no longer raise `ConfigurationError` and abort the
+  run. The directive whitelist validated names against `full` rather than the
+  operator registry, so the hard-set names 0.4.0 introduced — the very ones
+  ADR-12 and the README tell users to suppress per site — were rejected as
+  unknown operators. `# henitai:disable EqualityIdentityOperator` worked in
+  0.3.1; this restores it
+
+### Internal
+- Test-suite coupling to private implementation details is now guarded by
+  `spec/infra/private_method_reach_spec.rb`, a ratchet: every spec that reaches
+  a private method through `send` or an instance-variable poke carries a
+  documented budget, and a budget may only ever go down — beating one fails the
+  suite until the number is lowered in the same commit. Twelve tickets tracking
+  this debt had sat open while the debt itself moved into three *different*,
+  unticketed files, because nothing measured it
+- Nine collaborators extracted, each because a rule had no public seam rather
+  than to satisfy the ratchet mechanically: `Integration::ChildDebugLog` and
+  `Integration::LoadedFeatures` (replacing `Integration::ChildDebugSupport`,
+  which declared `private` at the top of the module); `SlotScheduler::SlotTable`,
+  `RetryPolicy`, `SlotDeadline`, `TestFileSelection` and `DrainVerdict`;
+  `ExcludedTestFilter`; `EquivalenceDetector::OperandPredicates`;
+  `DirtySourceDetector`, `SourceFileSelection`, `SubjectSelection` and
+  `RunnerDependencies`. `SlotScheduler` and `Runner` both shed enough code to
+  come back under their complexity budgets
+
 ## [0.4.0] - 2026-07-14
 
 ### Added
@@ -422,7 +506,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLI critical path: `henitai run` now executes the full pipeline, supports `--since`, returns CI-friendly exit codes, and `henitai version` prints `Henitai::VERSION`
 - RSpec per-test coverage output: `henitai/coverage_formatter` now writes `coverage/henitai_per_test.json`
 
-[Unreleased]: https://github.com/martinotten/henitai/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/martinotten/henitai/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/martinotten/henitai/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/martinotten/henitai/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/martinotten/henitai/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/martinotten/henitai/compare/v0.2.1...v0.3.0

data/README.md

@@ -43,7 +43,7 @@ Or install globally:
 gem install henitai
 ```
 
-**Requires Ruby 4.0.0+**
+**Requires Ruby 3.3.6+**
 
 ## Quick start
 

data/lib/henitai/cli.rb

@@ -78,7 +78,7 @@ module Henitai
 
     def help_text
       <<~HELP
-        Hen'i-tai 変異体 #{Henitai::VERSION} — Ruby 4 Mutation Testing
+        Hen'i-tai 変異体 #{Henitai::VERSION} — Ruby Mutation Testing
 
         Usage:
           henitai run [options] [SUBJECT_PATTERN...]

data/lib/henitai/configuration.rb

@@ -26,10 +26,17 @@ module Henitai
     DEFAULT_CHECKPOINT_EVERY = 200
     DEFAULT_CHECKPOINT_INTERVAL = 30.0
     DEFAULT_REPORTS_DIR = "reports"
+    # All three default to true because Result's MS numerator has always counted
+    # killed + timeout + runtime_error unconditionally. Until 0.5.0 this block
+    # was validated but never read, so the shipped `false` defaults described
+    # behavior the scorer did not have. Wiring it up with those defaults intact
+    # would have silently dropped timeouts and aborts out of every user's score;
+    # flipping them keeps the numerator exactly as it was and makes the knob
+    # mean what it says. See Result::CRITERION_STATUSES for the mapping.
     DEFAULT_COVERAGE_CRITERIA = {
       test_result: true,
-      timeout: false,
-      process_abort: false
+      timeout: true,
+      process_abort: true
     }.freeze
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
     CONFIG_FILE        = ".henitai.yml"

data/lib/henitai/dirty_source_detector.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Answers whether any configured source root has changed, which is what makes
+  # a prior run's survivor verdicts unsafe to reuse.
+  #
+  # Two change sets are considered together: files dirty in the worktree, and
+  # files committed since the run being reused. Test-only churn is deliberately
+  # ignored — a spec edit invalidates nothing about a *mutant*, only about
+  # whether it is still killed, which the survivor rerun is about to re-measure
+  # anyway.
+  #
+  # Every failure mode answers `true`. A wrong `true` costs one extra rerun; a
+  # wrong `false` silently reuses a stale verdict, which is the whole failure
+  # this guard exists to prevent.
+  class DirtySourceDetector
+    def initialize(includes:, git_diff_analyzer:)
+      @includes = includes
+      @git_diff_analyzer = git_diff_analyzer
+    end
+
+    def dirty?(dirty_worktree_files, git_sha: nil)
+      # A nil list means the worktree could not be read at all, not that it is
+      # clean.
+      return true if dirty_worktree_files.nil?
+
+      all_changed = dirty_worktree_files + committed_changed_files(git_sha)
+      all_changed.any? { |path| in_include_root?(normalize_path(path)) }
+    rescue StandardError
+      true
+    end
+
+    private
+
+    def committed_changed_files(git_sha)
+      return [] unless git_sha
+
+      @git_diff_analyzer.changed_files(from: git_sha, to: "HEAD")
+    end
+
+    def include_roots
+      @include_roots ||= Array(@includes).map { |path| normalize_path(path) }
+    end
+
+    # Prefix match on a path boundary, not a bare start_with?: "lib" must not
+    # match "library/foo.rb".
+    def in_include_root?(path)
+      include_roots.any? { |root| path == root || path.start_with?("#{root}/") }
+    end
+
+    def normalize_path(path) = File.expand_path(path)
+  end
+end

data/lib/henitai/equivalence_detector/operand_predicates.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  class EquivalenceDetector
+    # Recognizes the arithmetic operators and neutral operands that make a
+    # mutation provably equivalent to its original -- `x + 0`, `x * 1` and
+    # friends.
+    #
+    # Extracted from EquivalenceDetector because these decisions are
+    # load-bearing for scoring: a mutant marked equivalent leaves *both* sides
+    # of the mutation score, so a false positive quietly changes the reported
+    # number. They deserve tests of their own rather than being reached through
+    # the detector's private interface.
+    class OperandPredicates
+      ADDITIVE = %i[+ -].freeze
+      MULTIPLICATIVE = %i[* / **].freeze
+
+      def additive_operator?(operator) = ADDITIVE.include?(operator)
+
+      def multiplicative_operator?(operator) = MULTIPLICATIVE.include?(operator)
+
+      # Additive identity: `x + 0` and `x - 0` both reduce to `x`.
+      def zero_operand?(node) = numeric_operand?(node, 0)
+
+      # Multiplicative identity: `x * 1`, `x / 1` and `x ** 1` all reduce to `x`.
+      def one_operand?(node) = numeric_operand?(node, 1)
+
+      private
+
+      # Reads the right-hand operand of a binary send. Guards against a
+      # malformed node whose operand is a bare Ruby value rather than an AST
+      # node -- that shape does not occur in parsed source, but the detector
+      # must not raise on synthesized input.
+      def numeric_operand?(node, value)
+        operand = node.children[2]
+        return false unless operand.is_a?(Parser::AST::Node)
+
+        case operand.type
+        when :int, :float
+          operand.children.first == value || operand.children.first == value.to_i
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/henitai/equivalence_detector.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "parser_current"
+require_relative "equivalence_detector/operand_predicates"
 
 module Henitai
   # Detects obvious equivalent mutants before execution.
@@ -112,33 +113,15 @@ module Henitai
       node.is_a?(Parser::AST::Node) && node.type == type && node.children.empty?
     end
 
-    def additive_operator?(operator)
-      %i[+ -].include?(operator)
-    end
+    def additive_operator?(operator) = operand_predicates.additive_operator?(operator)
 
-    def multiplicative_operator?(operator)
-      %i[* / **].include?(operator)
-    end
+    def multiplicative_operator?(operator) = operand_predicates.multiplicative_operator?(operator)
 
-    def zero_operand?(node)
-      numeric_operand?(node, 0)
-    end
-
-    def one_operand?(node)
-      numeric_operand?(node, 1)
-    end
+    def zero_operand?(node) = operand_predicates.zero_operand?(node)
 
-    def numeric_operand?(node, value)
-      operand = node.children[2]
-      return false unless operand.is_a?(Parser::AST::Node)
+    def one_operand?(node) = operand_predicates.one_operand?(node)
 
-      case operand.type
-      when :int, :float
-        operand.children.first == value || operand.children.first == value.to_i
-      else
-        false
-      end
-    end
+    def operand_predicates = @operand_predicates ||= OperandPredicates.new
 
     # Detects `lhs == <singleton>` mutated to `lhs.equal?(<singleton>)` (or the
     # reverse), but only when the receiver is itself a singleton literal.

data/lib/henitai/excluded_test_filter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Drops test files matching any of the configured exclude globs.
+  #
+  # This keeps a mutant child from re-running tests that themselves spawn
+  # henitai or forked subprocesses -- the CLI and process-scheduler specs, when
+  # dogfooding henitai on itself -- which would otherwise multiply processes and
+  # log noise.
+  #
+  # Takes the pattern list rather than a configuration object: exclusion is a
+  # path-matching rule, and keeping it free of configuration lookup makes it
+  # directly testable.
+  class ExcludedTestFilter
+    # @param patterns [Array<String>, nil] exclude globs; nil and [] both mean
+    #   "exclude nothing"
+    def initialize(patterns:)
+      @patterns = Array(patterns)
+    end
+
+    # @param tests [Array<String>] candidate test paths
+    # @return [Array<String>] paths not matched by any pattern
+    def reject(tests)
+      return tests if @patterns.empty?
+
+      tests.reject { |path| excluded?(path) }
+    end
+
+    private
+
+    # FNM_PATHNAME so a single `*` does not match across a directory separator.
+    # Without it, an exclude as narrow as "spec/a/*_spec.rb" would swallow every
+    # test below spec/a as well.
+    def excluded?(path)
+      candidate = File.expand_path(path)
+      expanded_patterns.any? do |pattern|
+        File.fnmatch?(pattern, candidate, File::FNM_PATHNAME)
+      end
+    end
+
+    # Both sides are expanded so a relative pattern still matches an absolute
+    # test path, and vice versa.
+    def expanded_patterns
+      @expanded_patterns ||= @patterns.map { |pattern| File.expand_path(pattern) }
+    end
+  end
+end

data/lib/henitai/execution_engine.rb

@@ -109,19 +109,13 @@ module Henitai
       test_prioritizer(config).sort(tests, mutant, test_history(config))
     end
 
-    # Drops test files matching any config.test_excludes glob. Used to keep a
-    # mutant child from re-running tests that themselves spawn henitai/forked
-    # subprocesses (e.g. the CLI and process-scheduler specs when dogfooding
-    # henitai on itself), which otherwise multiplies processes and log noise.
     def reject_excluded_tests(tests, config)
-      patterns = config.respond_to?(:test_excludes) ? Array(config.test_excludes) : []
-      return tests if patterns.empty?
+      ExcludedTestFilter.new(patterns: configured_test_excludes(config)).reject(tests)
+    end
 
-      expanded = patterns.map { |pattern| File.expand_path(pattern) }
-      tests.reject do |path|
-        candidate = File.expand_path(path)
-        expanded.any? { |pattern| File.fnmatch?(pattern, candidate, File::FNM_PATHNAME) }
-      end
+    # Specs pass bare config doubles exposing only what the example needs.
+    def configured_test_excludes(config)
+      config.respond_to?(:test_excludes) ? config.test_excludes : nil
     end
 
     def test_prioritizer(config)

data/lib/henitai/inherited_fd_registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Tracks parent-process file handles that a forked child must not keep open.
+  #
+  # The motivating case is the reports-directory lock. `flock` is held on the
+  # open file *description*, which parent and child share after a fork. If a
+  # child outlives its parent while holding an inherited copy of that handle,
+  # the lock stays held by a process that is no longer running a mutation run,
+  # and every later invocation fails with a ConcurrentRunError naming a dead
+  # pid. Closing the child's copy immediately after fork means the lock dies
+  # with the parent, as intended.
+  #
+  # Registration is parent-side; #close_all! is the child-side call. The
+  # registry deliberately holds IO objects rather than file descriptor numbers:
+  # a child that recreated the handle via IO.for_fd would leave the original
+  # object alive, and its finalizer could later close a descriptor number the
+  # child had since reused for something else.
+  module InheritedFdRegistry
+    @ios = []
+    @mutex = Mutex.new
+
+    class << self
+      def register(io)
+        @mutex.synchronize { @ios << io }
+        io
+      end
+
+      def unregister(io)
+        @mutex.synchronize { @ios.delete(io) }
+        io
+      end
+
+      # @return [Array<IO>] copy of the tracked handles
+      def registered
+        @mutex.synchronize { @ios.dup }
+      end
+
+      # Closes every tracked handle. Call this in the child, immediately after
+      # Process.fork.
+      #
+      # This deliberately does NOT take the mutex. `fork` can land while
+      # another thread in the parent holds it -- the coverage bootstrap thread
+      # and the scheduler's worker threads both run concurrently with spawning
+      # -- and only the forking thread survives into the child. Waiting on a
+      # mutex whose owner does not exist there would hang the child forever.
+      # Reading a stale snapshot is harmless; deadlocking is not.
+      def close_all!
+        ios = @ios.dup
+        @ios = []
+        ios.each { |io| close_quietly(io) }
+        nil
+      end
+
+      private
+
+      # Runs in a just-forked child, where raising would take down the whole
+      # mutant run rather than the one handle that failed.
+      def close_quietly(io)
+        io.close unless io.closed?
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/integration/base.rb

@@ -2,7 +2,7 @@
 
 require "stringio"
 require_relative "../process_wakeup"
-require_relative "child_debug_support"
+require_relative "child_debug_log"
 require_relative "child_runtime_control"
 require_relative "scenario_log_support"
 
@@ -13,9 +13,14 @@ module Henitai
     # environment helpers. Concrete adapters mix in MutantRunSupport and
     # implement #run_tests plus test selection.
     class Base
-      include ChildDebugSupport
       include ChildRuntimeControl
 
+      # Child-run diagnostics. Public so the child-side modules mixed into
+      # concrete adapters can reach it without `send`.
+      def child_debug_log
+        @child_debug_log ||= ChildDebugLog.new
+      end
+
       # @param subject [Subject]
       # @return [Array<String>] paths to test files that cover this subject
       def select_tests(subject)

data/lib/henitai/integration/child_bootstrap.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # The first thing a forked mutant child does, before any test-framework
+    # work begins.
+    #
+    # Extracted from the fork block so the sequence is named and unit-testable
+    # without forking, and so both the RSpec and Minitest paths -- which share
+    # MutantRunSupport#spawn_mutant -- get identical treatment.
+    module ChildBootstrap
+      # @param parent_pid [Integer] captured in the parent *before* Process.fork.
+      #   Reading Process.ppid here instead would race the very death the
+      #   watchdog is looking for: a parent that dies between fork and this
+      #   line leaves the child with ppid 1 as its baseline, making it look
+      #   permanently healthy.
+      def self.after_fork!(parent_pid:)
+        # First, so that even a crash later in this method releases the
+        # reports-directory lock rather than pinning it with an inherited fd.
+        InheritedFdRegistry.close_all!
+        Process.setpgid(0, 0)
+        OrphanWatchdog.start(parent_pid:)
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/integration/child_debug_log.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "loaded_features"
+
+module Henitai
+  module Integration
+    # Diagnostics writer for the mutant child process, gated on
+    # `HENITAI_DEBUG_CHILD=1`.
+    #
+    # Every method gates on {#enabled?} itself rather than trusting call sites,
+    # so no unguarded caller can leak debug lines into every child log by
+    # default.
+    class ChildDebugLog
+      PREFIX = "[henitai-debug-child]"
+
+      def initialize(io: nil, loaded_features: LoadedFeatures.new)
+        @io = io
+        @loaded_features = loaded_features
+      end
+
+      def enabled? = ENV["HENITAI_DEBUG_CHILD"] == "1"
+
+      def write(message)
+        return unless enabled?
+
+        io.puts(message)
+        io.flush
+      end
+
+      def rspec_trace(test_files:, rspec_options:, rspec_argv:)
+        return unless enabled?
+
+        write(
+          "#{PREFIX} cwd=#{Dir.pwd}\n" \
+          "#{PREFIX} files_exist=#{test_files.map { |file| [file, File.exist?(file)] }.inspect}\n" \
+          "#{PREFIX} loaded_features_check=#{@loaded_features.map(test_files).inspect}\n" \
+          "#{PREFIX} test_files=#{test_files.inspect}\n" \
+          "#{PREFIX} rspec_options=#{rspec_options.inspect}\n" \
+          "#{PREFIX} rspec_argv=#{rspec_argv.inspect}"
+        )
+      end
+
+      def rspec_exit(status)
+        write("#{PREFIX} RSpec result=#{status.inspect}")
+      end
+
+      def example_count(stage)
+        return unless enabled?
+
+        write("#{PREFIX} rspec_world_example_count_#{stage}=#{rspec_world_example_count.inspect}")
+      end
+
+      def activation_start(mutant_id)
+        write("#{PREFIX} activate_start mutant=#{mutant_id}")
+      end
+
+      def activation_end(activation_result, test_files:)
+        write(
+          "#{PREFIX} activate_end result=#{activation_result.inspect}\n" \
+          "#{PREFIX} run_tests_start test_files=#{test_files.inspect}"
+        )
+      end
+
+      def mutant_meta(mutant)
+        return unless enabled?
+
+        write(
+          "#{PREFIX} mutant_meta stableId=#{value_of(mutant, :stable_id)}\n" \
+          "#{PREFIX} mutant_meta operator=#{value_of(mutant, :operator)}\n" \
+          "#{PREFIX} mutant_meta subject=#{subject_expression_of(mutant)}\n" \
+          "#{PREFIX} mutant_meta location=#{location_of(mutant)}\n"
+        )
+      end
+
+      # Reports where Runner#resolve_subjects was loaded from, which is how a
+      # child that activated a mutant on Henitai's own source is identified.
+      def activation_check
+        return unless enabled?
+
+        location = begin
+          Henitai::Runner.instance_method(:resolve_subjects).source_location&.join(":") # henitai:disable
+        rescue StandardError
+          nil
+        end
+
+        write("#{PREFIX} activation_check resolve_subjects_location=#{location}\n")
+      end
+
+      def timeout_signal_sent(pid)
+        write("#{PREFIX} timeout_signal_sent pid=#{pid}")
+      end
+
+      def thread_dump(reason)
+        return unless enabled?
+
+        write("#{PREFIX} thread_dump reason=#{reason}")
+        Thread.list.each_with_index { |thread, index| dump_thread(thread, index) }
+      end
+
+      def rspec_world_example_count
+        ::RSpec.world.example_count
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def dump_thread(thread, index)
+        write(
+          "#{PREFIX} thread index=#{index} id=#{thread.object_id} " \
+          "status=#{thread.status.inspect}"
+        )
+        Array(thread.backtrace).each { |line| write("#{PREFIX}   #{line}") }
+      end
+
+      def value_of(mutant, name) = mutant.respond_to?(name) ? mutant.public_send(name) : nil
+
+      # Deliberately `.inspect` inside the ternary, not on the result: a mutant
+      # without #location must render as empty, not as the string "nil".
+      def location_of(mutant) = mutant.respond_to?(:location) ? mutant.location.inspect : nil
+
+      def subject_expression_of(mutant)
+        return nil unless mutant.respond_to?(:subject) && mutant.subject.respond_to?(:expression)
+
+        mutant.subject.expression
+      end
+
+      # Resolved per call, never memoized: ScenarioLogSupport#capture_child_output
+      # reassigns $stdout inside the child *after* this object is built, so a
+      # captured-at-construction stream would send every debug line to the
+      # parent's terminal instead of the child's log file.
+      def io = @io || $stdout
+    end
+  end
+end

data/lib/henitai/integration/child_runtime_control.rb

@@ -17,10 +17,13 @@ module Henitai
         CoverageRuntimeSuppressors.suppress_coverage!
       end
 
+      # Signalling, not logging: the thread dump itself is emitted by the
+      # child's USR1 handler, so this only asks for it and gives the child a
+      # moment to write before the caller tears the process group down.
       def debug_child_timeout_dump(pid)
-        return unless debug_child?
+        return unless child_debug_log.enabled?
 
-        debug_child_puts("[henitai-debug-child] timeout_signal_sent pid=#{pid}")
+        child_debug_log.timeout_signal_sent(pid)
         Process.kill(:USR1, pid)
         pause(0.2)
       rescue Errno::ESRCH
@@ -28,22 +31,7 @@ module Henitai
       end
 
       def install_debug_timeout_trap
-        Signal.trap("USR1") { debug_child_thread_dump("timeout") }
-      end
-
-      def debug_child_thread_dump(reason)
-        return unless debug_child?
-
-        debug_child_puts("[henitai-debug-child] thread_dump reason=#{reason}")
-        Thread.list.each_with_index do |thread, index|
-          debug_child_puts(
-            "[henitai-debug-child] thread index=#{index} id=#{thread.object_id} " \
-            "status=#{thread.status.inspect}"
-          )
-          Array(thread.backtrace).each do |line|
-            debug_child_puts("[henitai-debug-child]   #{line}")
-          end
-        end
+        Signal.trap("USR1") { child_debug_log.thread_dump("timeout") }
       end
     end
   end