henitai 0.3.1 → 0.5.0

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

data/lib/henitai/integration/loaded_features.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Answers whether a test file has already been required, by matching it
+    # against `$LOADED_FEATURES`.
+    #
+    # Both sides need normalizing: `$LOADED_FEATURES` holds absolute paths for
+    # required files but callers hand over repository-relative test paths, and
+    # either side may or may not carry the `.rb` suffix. A feature string that
+    # cannot be expanded (invalid encoding, for instance) falls back to its raw
+    # form rather than aborting the whole check — this runs inside a mutant
+    # child whose only job is diagnostics.
+    class LoadedFeatures
+      def include?(file)
+        candidates = candidates_for(file)
+        $LOADED_FEATURES.any? do |feature|
+          candidates.include?(feature) || candidates.include?(normalize(feature))
+        end
+      end
+
+      def map(files) = files.map { |file| [file, include?(file)] }
+
+      private
+
+      def candidates_for(file)
+        expanded = File.expand_path(file)
+        [expanded, "#{expanded}.rb", file, "#{file}.rb"].uniq
+      end
+
+      def normalize(feature)
+        File.expand_path(feature)
+      rescue StandardError
+        feature
+      end
+    end
+  end
+end

data/lib/henitai/integration/mutant_run_support.rb

@@ -47,7 +47,7 @@ module Henitai
         with_subprocess_env do
           suppress_simplecov!
           suppress_coverage!
-          install_debug_timeout_trap if debug_child?
+          install_debug_timeout_trap if child_debug_log.enabled?
           with_non_interactive_stdin do
             run_child_activation_and_tests(mutant:, test_files:, log_paths:)
           end
@@ -63,11 +63,11 @@ module Henitai
       def run_child_activation_and_tests(mutant:, test_files:, log_paths:)
         scenario_log_support.with_coverage_dir(mutant.id) do
           scenario_log_support.capture_child_output(log_paths) do
-            debug_child_mutant_meta(mutant) if debug_child?
-            debug_child_activation_start(mutant.id)
+            child_debug_log.mutant_meta(mutant)
+            child_debug_log.activation_start(mutant.id)
             activation_result = Mutant::Activator.activate!(mutant)
-            debug_child_activation_check if debug_child?
-            debug_child_activation_end(activation_result, test_files:)
+            child_debug_log.activation_check
+            child_debug_log.activation_end(activation_result, test_files:)
             activation_result == :compile_error ? 2 : run_tests(test_files)
           end
         end

data/lib/henitai/integration/rspec_child_runner.rb

@@ -9,19 +9,20 @@ module Henitai
       private
 
       def run_rspec_runner(test_files)
-        debug_child_puts("[henitai-debug-child] build_rspec_runner_start")
+        log = child_debug_log
+        log.write("[henitai-debug-child] build_rspec_runner_start")
         runner = build_rspec_runner
-        debug_child_puts("[henitai-debug-child] build_rspec_runner_return")
-        debug_child_puts("[henitai-debug-child] configure_rspec_runner_start")
+        log.write("[henitai-debug-child] build_rspec_runner_return")
+        log.write("[henitai-debug-child] configure_rspec_runner_start")
         configure_rspec_runner(runner)
-        debug_child_puts("[henitai-debug-child] configure_rspec_runner_return")
+        log.write("[henitai-debug-child] configure_rspec_runner_return")
         load_rspec_spec_files(test_files)
         run_rspec_specs(runner)
       rescue SystemExit => e
-        debug_child_puts("[henitai-debug-child] runner_run_system_exit status=#{e.status.inspect}")
+        log.write("[henitai-debug-child] runner_run_system_exit status=#{e.status.inspect}")
         raise
       ensure
-        debug_child_puts("[henitai-debug-child] runner_run_ensure")
+        child_debug_log.write("[henitai-debug-child] runner_run_ensure")
       end
 
       def build_rspec_runner
@@ -32,28 +33,28 @@ module Henitai
       end
 
       def configure_rspec_runner(runner)
-        debug_child_puts("[henitai-debug-child] trap_interrupt_start")
+        child_debug_log.write("[henitai-debug-child] trap_interrupt_start")
         ::RSpec::Core::Runner.__send__(:trap_interrupt)
-        debug_child_puts("[henitai-debug-child] trap_interrupt_return")
-        debug_child_puts("[henitai-debug-child] runner_configure_start")
+        child_debug_log.write("[henitai-debug-child] trap_interrupt_return")
+        child_debug_log.write("[henitai-debug-child] runner_configure_start")
         runner.send(:configure, $stderr, $stdout)
-        debug_child_puts("[henitai-debug-child] runner_configure_return")
+        child_debug_log.write("[henitai-debug-child] runner_configure_return")
       end
 
       def load_rspec_spec_files(test_files)
-        debug_child_puts("[henitai-debug-child] load_spec_files_start")
+        child_debug_log.write("[henitai-debug-child] load_spec_files_start")
         ::RSpec.configuration.files_to_run = test_files.map do |file|
           File.expand_path(file)
         end
         ::RSpec.configuration.load_spec_files
-        debug_child_example_count("after_load")
-        debug_child_puts("[henitai-debug-child] load_spec_files_return")
+        child_debug_log.example_count("after_load")
+        child_debug_log.write("[henitai-debug-child] load_spec_files_return")
       end
 
       def run_rspec_specs(runner)
-        debug_child_puts("[henitai-debug-child] run_specs_start")
+        child_debug_log.write("[henitai-debug-child] run_specs_start")
         result = runner.send(:run_specs, ::RSpec.world.ordered_example_groups)
-        debug_child_puts("[henitai-debug-child] run_specs_return result=#{result.inspect}")
+        child_debug_log.write("[henitai-debug-child] run_specs_return result=#{result.inspect}")
         result
       end
     end

data/lib/henitai/integration/rspec_process_runner.rb

@@ -32,7 +32,7 @@ module Henitai
           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 = @intervals.reverse_each.find { |i| i[:pid] == pid && i[:ended_at].nil? }
             entry[:ended_at] = ended_at if entry
           end
         end
@@ -84,8 +84,13 @@ module Henitai
       # 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:)
+        # Captured here, in the parent. Reading Process.ppid inside the child
+        # would race the very death the watchdog looks for: a parent dying
+        # between fork and that read leaves the child with ppid 1 as its
+        # baseline, so it would never consider itself orphaned.
+        parent_pid = Process.pid
         pid = Process.fork do
-          Process.setpgid(0, 0)
+          ChildBootstrap.after_fork!(parent_pid:)
           ENV["HENITAI_MUTANT_ID"] = mutant.id
           Process.exit(
             integration.run_in_child(

data/lib/henitai/integration.rb

@@ -3,10 +3,12 @@
 require "fileutils"
 require "stringio"
 require_relative "process_wakeup"
+require_relative "integration/child_bootstrap"
 require_relative "integration/rspec_process_runner"
 require_relative "integration/scenario_log_support"
 require_relative "integration/coverage_suppression"
-require_relative "integration/child_debug_support"
+require_relative "integration/child_debug_log"
+require_relative "integration/loaded_features"
 require_relative "integration/base"
 require_relative "integration/mutant_run_support"
 require_relative "integration/rspec_child_runner"
@@ -111,13 +113,14 @@ module Henitai
       def run_tests(test_files)
         require "rspec/core"
         ::RSpec.__send__(:configuration).fail_if_no_examples = true
-        debug_child_rspec_trace(test_files:, rspec_options: [], rspec_argv: test_files)
-        debug_child_example_count("before_run") # steep:ignore Ruby::NoMethod
-        debug_child_puts("[henitai-debug-child] runner_run_start")
+        log = child_debug_log
+        log.rspec_trace(test_files:, rspec_options: [], rspec_argv: test_files)
+        log.example_count("before_run")
+        log.write("[henitai-debug-child] runner_run_start")
         status = run_rspec_runner(test_files)
-        debug_child_puts("[henitai-debug-child] runner_run_return status=#{status.inspect}")
-        debug_child_example_count("after_run") # steep:ignore Ruby::NoMethod
-        debug_child_rspec_exit(status)
+        log.write("[henitai-debug-child] runner_run_return status=#{status.inspect}")
+        log.example_count("after_run")
+        log.rspec_exit(status)
         return status if status.is_a?(Integer)
 
         status == true ? 0 : 1

data/lib/henitai/mutation_skip_directives.rb

@@ -25,7 +25,13 @@ module Henitai
   # Matching mutants are reported as ignored by {StaticFilter}, not dropped.
   class MutationSkipDirectives
     DIRECTIVE = /\A#\s*henitai:disable(?<kind>-start|-end)?(?<rest>[:\s].*)?\z/
-    VALID_OPERATOR_NAMES = Operator::FULL_SET
+
+    # The whitelist is the operator *registry*, not the configured set: the
+    # widest set names every operator henitai knows. Narrowing it to the
+    # configured set would reject a directive for a registered operator the
+    # current run happens not to enable — hard-set names above all, which is
+    # precisely where the escape hatch is needed (ADR-12).
+    VALID_OPERATOR_NAMES = Operator::HARD_SET
 
     # A parsed directive: +operators+ is nil (all) or a Set of canonical
     # operator names; +reason+ is optional free text shown in reports.

data/lib/henitai/operator.rb

@@ -44,13 +44,23 @@ module Henitai
       AssignmentExpression
       UnaryOperator
       UpdateOperator
+    ]).freeze
+
+    # Usually-unkillable operators on top of full: mutations whose survival
+    # rarely indicates a test gap (framework key normalization, the
+    # ==/eql?/equal? pairing). Opt in when hunting the last survivors
+    # (ADR-12).
+    HARD_SET = (FULL_SET + %w[
       EqualityIdentityOperator
+      HashKeyType
     ]).freeze
 
-    # @param set [Symbol] :light or :full
+    SETS = { light: LIGHT_SET, full: FULL_SET, hard: HARD_SET }.freeze
+
+    # @param set [Symbol] :light, :full or :hard
     # @return [Array<Operator>] operator instances for the given set
     def self.for_set(set)
-      names = set.to_sym == :full ? FULL_SET : LIGHT_SET
+      names = SETS.fetch(set.to_sym, LIGHT_SET)
       names.map { |name| Henitai::Operators.const_get(name).new }
     end
 

data/lib/henitai/operators/hash_key_type.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Operators
+    # Mutates symbol hash keys into string keys, one pair at a time
+    # (`{ a: 1 }` -> `{ "a" => 1 }`). Symbol/string key confusion is a real
+    # defect class, but frameworks that normalize keys (e.g. ActiveRecord's
+    # `order`/`where`) make these mutants frequently unkillable — hence the
+    # hard set, not full (ADR-12).
+    class HashKeyType < Henitai::Operator
+      NODE_TYPES = [:hash].freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        node.children.each_with_index.filter_map do |pair, index|
+          next unless symbol_key_pair?(pair)
+
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: mutated_hash(node, index),
+            description: "replaced symbol key with string key"
+          )
+        end
+      end
+
+      private
+
+      def symbol_key_pair?(node)
+        node.type == :pair && node.children.first&.type == :sym
+      end
+
+      def mutated_hash(node, index)
+        pairs = node.children.each_with_index.map do |pair, pair_index|
+          pair_index == index ? stringified_pair(pair) : pair
+        end
+        Parser::AST::Node.new(:hash, pairs)
+      end
+
+      def stringified_pair(pair)
+        key, value = pair.children
+        string_key = Parser::AST::Node.new(:str, [key.children.first.to_s])
+        Parser::AST::Node.new(:pair, [string_key, value])
+      end
+    end
+  end
+end

data/lib/henitai/operators/hash_literal.rb

@@ -4,7 +4,10 @@ require_relative "../parser_current"
 
 module Henitai
   module Operators
-    # Reduces hash literals by emptying them or mutating symbol keys.
+    # Reduces hash literals: empties the whole hash and removes one pair at a
+    # time. Symbol-key -> string-key mutation lives in {HashKeyType} (hard
+    # set) because framework key normalization makes it frequently unkillable
+    # (ADR-12).
     class HashLiteral < Henitai::Operator
       NODE_TYPES = [:hash].freeze
 
@@ -16,7 +19,7 @@ module Henitai
         return [] if node.children.empty?
 
         mutants = [empty_hash_mutant(node, subject:)]
-        mutants.concat(symbol_key_mutants(node, subject:))
+        mutants.concat(pair_removal_mutants(node, subject:))
         mutants
       end
 
@@ -31,35 +34,31 @@ module Henitai
         )
       end
 
-      def symbol_key_mutants(node, subject:)
+      # Removing the only entry would duplicate the empty-hash mutant.
+      def pair_removal_mutants(node, subject:)
+        return [] if node.children.size < 2
+
         node.children.each_with_index.filter_map do |pair, index|
-          next unless symbol_key_pair?(pair)
+          next unless pair.type == :pair
 
           build_mutant(
             subject:,
             original_node: node,
-            mutated_node: mutated_hash(node, index),
-            description: "replaced symbol key with string key"
+            mutated_node: hash_without_pair(node, index),
+            description: "removed hash pair #{pair_key_label(pair)}"
           )
         end
       end
 
-      def symbol_key_pair?(node)
-        node.type == :pair && node.children.first&.type == :sym
-      end
-
-      def mutated_hash(node, pair_index)
-        mutated_pairs = node.children.each_with_index.map do |pair, index|
-          index == pair_index ? mutated_pair(pair) : pair
-        end
-
-        Parser::AST::Node.new(:hash, mutated_pairs)
+      def hash_without_pair(node, pair_index)
+        remaining = node.children.reject.with_index { |_pair, index| index == pair_index }
+        Parser::AST::Node.new(:hash, remaining)
       end
 
-      def mutated_pair(pair)
-        key, value = pair.children
-        mutated_key = Parser::AST::Node.new(:str, [key.children.first.to_s])
-        Parser::AST::Node.new(:pair, [mutated_key, value])
+      # Pair keys are always AST nodes (sym/str/…); their first child is the
+      # literal value used purely as a human-readable label.
+      def pair_key_label(pair)
+        pair.children.first.children.first
       end
     end
   end

data/lib/henitai/operators/return_value.rb

@@ -65,7 +65,7 @@ module Henitai
         body = method_node.children.last
         return body unless body&.type == :begin
 
-        body.children.rfind { |child| child.is_a?(Parser::AST::Node) }
+        body.children.reverse_each.find { |child| child.is_a?(Parser::AST::Node) }
       end
 
       # rubocop:disable Lint/BooleanSymbol

data/lib/henitai/operators.rb

@@ -16,6 +16,7 @@ module Henitai
     autoload :ReturnValue, "henitai/operators/return_value"
     autoload :ArrayDeclaration, "henitai/operators/array_declaration"
     autoload :HashLiteral, "henitai/operators/hash_literal"
+    autoload :HashKeyType, "henitai/operators/hash_key_type"
     autoload :RangeLiteral, "henitai/operators/range_literal"
     autoload :SafeNavigation, "henitai/operators/safe_navigation"
     autoload :PatternMatch, "henitai/operators/pattern_match"

data/lib/henitai/orphan_watchdog.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Makes a forked mutant child exit when its parent dies.
+  #
+  # Children `setpgid(0, 0)` into 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. If the parent is SIGKILLed, OOM-killed, or
+  # crashes, its children receive no signal at all: they reparent to init and
+  # keep running, each holding a full Ruby and test-framework image. Runs have
+  # been observed leaving a dozen such orphans behind, several gigabytes in
+  # total.
+  #
+  # A child cannot be told to die by a parent that is already gone, so it has
+  # to notice by itself. This is a poll: portable, and cheap enough at a
+  # multi-second interval that it costs nothing next to running a test suite.
+  # PDEATHSIG (Linux) and kqueue NOTE_EXIT (macOS) would be prompter but are
+  # platform-specific; they can be layered on later behind the same interface.
+  class OrphanWatchdog
+    DEFAULT_INTERVAL = 1.5
+    ENV_ENABLED = "HENITAI_CHILD_WATCHDOG"
+    ENV_INTERVAL = "HENITAI_CHILD_WATCHDOG_INTERVAL"
+
+    # Exit code used when the watchdog fires. 2 classifies as :compile_error
+    # (see ScenarioExecutionResult.status_for), which surfaces in reports and
+    # logs. Codes at 3 and above classify as :killed, which would let a
+    # false positive silently inflate the mutation score -- so a visibly wrong
+    # verdict is preferred to an invisibly wrong one. In the true-positive case
+    # the parent is dead and nothing classifies this child at all.
+    ORPHAN_EXIT_CODE = 2
+
+    # Captured at load time, for the same reason as ProcessLiveness::KILL: the
+    # mutant child runs the host project's own suite, and a spec there stubbing
+    # `Process.ppid` would otherwise make this child believe it had been
+    # reparented and exit itself.
+    PPID = Process.method(:ppid)
+
+    # Opt-OUT, deliberately inverted relative to HENITAI_DEBUG_CHILD's opt-in:
+    # a watchdog that defaulted to off would never protect the runs it exists
+    # for. Set HENITAI_CHILD_WATCHDOG=0 to disable.
+    def self.enabled?(env = ENV)
+      env[ENV_ENABLED] != "0"
+    end
+
+    def self.poll_interval(env = ENV)
+      seconds = Float(env[ENV_INTERVAL], exception: false)
+      seconds&.positive? ? seconds : DEFAULT_INTERVAL
+    end
+
+    # Starts the watchdog in a background thread. Call in the child, right
+    # after fork, with the pid captured in the parent beforehand.
+    #
+    # @return [Thread, nil] nil when disabled
+    def self.start(parent_pid:, env: ENV)
+      return nil unless enabled?(env)
+
+      watchdog = new(parent_pid:, interval: poll_interval(env))
+      Thread.new { watchdog.run }
+    end
+
+    # Every collaborator is injectable so the decision logic can be specced
+    # without forking a process or waiting on a real clock.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(parent_pid:, interval: DEFAULT_INTERVAL, liveness: ProcessLiveness,
+                   ppid: PPID, on_orphan: nil, sleeper: nil)
+      @parent_pid = parent_pid
+      @interval   = interval
+      @liveness   = liveness
+      @ppid       = ppid
+      @on_orphan  = on_orphan || -> { Kernel.exit!(ORPHAN_EXIT_CODE) }
+      @sleeper    = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Two arms, because neither alone is sufficient. A changed ppid is
+    # definitive -- we have been reparented, and no pid reuse can fake that --
+    # but it stays equal while the parent lingers as a zombie, which the
+    # liveness probe catches.
+    def orphaned?
+      @ppid.call != @parent_pid || !@liveness.alive?(@parent_pid)
+    end
+
+    # Polls until orphaned, then hands over to the orphan handler -- which by
+    # default calls exit! and so never returns. Checks before sleeping, so a
+    # child forked from an already-dead parent dies immediately rather than
+    # after one interval.
+    def run
+      @sleeper.call(@interval) until orphaned?
+
+      @on_orphan.call
+    end
+  end
+end