henitai 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 425e1946a343ce94a9172939a8ad5c5d49e01fe86fbf2b01326b2f0be068df85
-  data.tar.gz: 85867b98b26cb3710d0c1e56bd4b37b5ba78f08f47ad8378dc76ae07ce1dfc9a
+  metadata.gz: 34e96b6bb2bd74ac49e52a2acbe459ccb551498914d8b442f56c427c8b8ef45c
+  data.tar.gz: 2792932da92f73f6e4cfcc0a67aa28dca405fd4cee6d02437e13f76fbd9ee08d
 SHA512:
-  metadata.gz: f0de6ea6a0a5a830a917f1097ac243ce43c6b8bf3bcc44ac1967133288770746d9c4df8fdee6609081613bfa174be5169e13143a22f1d3d22e8f74fd0cc008d7
-  data.tar.gz: 37eedd8f351dbd8a9094c668ce7c56560186936f0953b098f740b6cee1654971d1b5402efe2fd0d5650442b701af7fedaea257ec9f7827575f3f04c052c2593a
+  metadata.gz: 5fe64e42c96aaa19d26bdf1a45631146bea7cb6d8caca5891d75ac6da0bdb3c30843ea8a83e34a67d0f90559fe41229d46a7000478cdd3708fb7929efea9f209
+  data.tar.gz: 39432815b88d834f6eb30be76255240b8124339505a86d8f644f2cd48ad787d85c6eb9ea9e7a85191262540e06ac467a9c32ad326a306e10953d9e758355d7bf

data/CHANGELOG.md

@@ -7,6 +7,107 @@ 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
+- `hard` operator set (`mutation.operators: hard` / `--operators hard`), a
+  strict superset of `full` for usually-unkillable mutations (ADR-12):
+  currently `EqualityIdentityOperator` and the new `HashKeyType`
+  (`{ a: 1 }` -> `{ "a" => 1 }`) — framework key normalization (e.g.
+  ActiveRecord `order`/`where`) makes key-type mutants frequently equivalent
+- `HashLiteral` gains per-pair removal (`{ a: 1, b: 2 }` -> `{ b: 2 }`);
+  single-pair hashes and double-splat entries are skipped
+
+### Changed
+- `full` now means "usually killable": the symbol-key -> string-key mutation
+  moved from `HashLiteral` into the new hard-set `HashKeyType`, and
+  `EqualityIdentityOperator` moved from `full` to `hard` — `full` runs emit
+  fewer, higher-signal mutants
+
 ## [0.3.1] - 2026-07-13
 
 ### Fixed
@@ -405,7 +506,9 @@ 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.3.1...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
 [0.2.1]: https://github.com/martinotten/henitai/compare/v0.2.0...v0.2.1

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
 
@@ -271,7 +271,17 @@ The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/wor
 - `AssignmentExpression` — mutate compound assignment
 - `UnaryOperator` — remove unary `-` and `~`
 - `UpdateOperator` — swap compound assignments (`+=`↔`-=`, `*=`↔`/=`, `||=`↔`&&=`)
+
+**Hard** — adds usually-unkillable mutations on top of full, for hunting the
+last survivors (see [ADR-12](docs/architecture/adr/ADR-12-hard-operator-set.md)):
+
 - `EqualityIdentityOperator` — `==` ↔ `eql?`/`equal?` (hardest equality pairing to kill; see [ADR-10](docs/architecture/adr/ADR-10-split-equality-identity-mutations.md))
+- `HashKeyType` — `{ a: 1 }` → `{ "a" => 1 }` (frameworks that normalize key
+  types, e.g. ActiveRecord `order`/`where`, make these mutants equivalent at
+  many call sites; disable per site with `# henitai:disable HashKeyType`)
+
+`HashLiteral` (full set) empties the hash and removes one pair at a time
+(`{ a: 1, b: 2 }` → `{}` / `{ b: 2 }`).
 
 ## Stryker Dashboard integration
 

data/assets/schema/henitai.schema.json

@@ -44,7 +44,7 @@
       "additionalProperties": false,
       "properties": {
         "operators": {
-          "enum": ["light", "full"]
+          "enum": ["light", "full", "hard"]
         },
         "timeout": {
           "type": "number"

data/lib/henitai/cli/operator_command.rb

@@ -14,7 +14,8 @@ module Henitai
         "StringLiteral" => ["String literals", '"foo" -> ""'],
         "ReturnValue" => ["Return expressions", "return x -> return nil"],
         "ArrayDeclaration" => ["Array literals", "[1, 2] -> []"],
-        "HashLiteral" => ["Hash literals", "{ a: 1 } -> {}"],
+        "HashLiteral" => ["Hash literals", "{ a: 1, b: 2 } -> {} / { b: 2 }"],
+        "HashKeyType" => ["Hash key types", '{ a: 1 } -> { "a" => 1 }'],
         "RangeLiteral" => ["Range literals", "1..5 -> 1...5"],
         "SafeNavigation" => ["Safe navigation", "user&.name -> user.name"],
         "PatternMatch" => ["Pattern matching", "in { x: Integer } -> in { x: String }"],

data/lib/henitai/cli/run_options.rb

@@ -21,7 +21,7 @@ module Henitai
       end
 
       def add_operator_option(opts, options)
-        opts.on("--operators SET", "Operator set: light | full") do |set|
+        opts.on("--operators SET", "Operator set: light | full | hard") do |set|
           options[:operators] = set
         end
       end

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/configuration_validator.rb

@@ -33,7 +33,7 @@ module Henitai
     VALID_THRESHOLDS_KEYS = %i[high low].freeze
     VALID_DASHBOARD_KEYS = %i[project base_url].freeze
     VALID_INTEGRATION_KEYS = %i[name].freeze
-    VALID_OPERATORS = %i[light full].freeze
+    VALID_OPERATORS = %i[light full hard].freeze
     VALIDATION_STEPS = %i[
       validate_top_level_keys
       validate_integration

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