active_mutator 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a334e2726728421ba66d6a08db715587b8e0439b934489857b70d746912e89b8
-  data.tar.gz: cdce7a7856fd4b1f68b4cbf9dc5a62d58a1926555b203a01474d64aa95b6fbbe
+  metadata.gz: cf0b7bed1f6b35d6ab688affd01cb2ccc362944019ae5c18bff2e1205cccb53e
+  data.tar.gz: 9b4d7cac2fc3f8e3a6d737db4aa7f3b8f3f46c00baa275669fecbc5752e50910
 SHA512:
-  metadata.gz: d1cfeffd4210a83fcd974a3b175eabf0da02a54b7d253664e3252ed5fc0487fd60fcf4ad3db54d29d12e53363842e0a5116e0602c6ce83a971813e8895a84dbf
-  data.tar.gz: d21dae9ed1a6e6b668517ad99130a7a6e2d7de6d6f9ebf4f620de5ce7e0690bc81d105e8f3d78aff72c288034a2366ae6a0dced6a35d2101b63421fde0ef1da0
+  metadata.gz: f2ed986856e22c4881936ae20f66bac4ecdc57b31239b5786942be6c2128516db64542be9185da5f9e8bc06ad1acd893d9e231602e1cf553ad7c74d60af9ef61
+  data.tar.gz: 8f8bd75ed8572b8e1eee883644b412bc9e718eeb0b85f35e22d8f27b6f937113c505bccadca869fd33546895bbf68126a30b9931fc755c3df8d71e33b8168bb0

data/README.md

@@ -127,12 +127,26 @@ Each character on the progress line is one mutant, printed as it finishes:
 | `A` | `accepted` | matches a known-equivalent entry in the acceptance ledger. Excluded from the score |
 
 `invalid` mutants (edits that don't even re-parse as valid Ruby) are
-discarded before scheduling and reported as a count only. Exit code is `1`
-if unaccepted survivors or errors exist (or, with `--fail-at`, if the score
-is below the threshold), `0` otherwise, including when there are only
-`uncovered` or `accepted` results. The JSON report's `exit_reason` field
-(`unaccepted_survivors`, `worker_errors`, `clean`, `empty_plan`) is
-independent of the `--fail-at` gate. A `--since` or `--subject` run that
+discarded before scheduling and reported as a count only.
+
+| Exit | When |
+|---|---|
+| `0` | no unaccepted survivors or errors (only `uncovered` or `accepted` results count as clean), or the score meets `--fail-at` |
+| `1` | unaccepted survivors or errors (with `--fail-at`, only when the score is below it), or an empty plan (below) |
+| `2` | a usage or setup problem: a bad flag or config file, or a red baseline suite |
+| `3` | the run reached `--max-rss` and stopped |
+| `130` | the run was stopped by SIGINT (Ctrl-C) |
+| `143` | the run was stopped by SIGTERM (130 before 0.7.0) |
+
+A stopped run (`3`, `130`, `143`) kills its child processes, prints the
+summary for the mutants that finished with a `Partial mutation score:`
+line in place of `Mutation score:`, and never passes, whatever `--fail-at`
+says. See [Run diagnostics](docs/guides/diagnostics.md#aborted-runs).
+
+The JSON report's `exit_reason` field (`unaccepted_survivors`,
+`worker_errors`, `clean`, `empty_plan`, and for a stopped run `interrupted`
+or `memory_ceiling`) is independent of the `--fail-at` gate. `complete` is
+`false` only for a stopped run. A `--since` or `--subject` run that
 plans zero mutants skips the baseline, prints the usual count block with
 every status at `0` and no `Mutation score:` line (JSON: `score` is `null`,
 `exit_reason` is `empty_plan`), then warns with the cause and exits `1`
@@ -267,9 +281,12 @@ itself whether that emptiness is fine:
   blank lines, added or deleted. A magic comment such as
   `# frozen_string_literal: true` counts as code, and so does a file that
   fails to parse.
+- **Exit 0** when a file only lost code and no method spans the spot, e.g.
+  a whole method was removed. A deletion inside a method makes `--since`
+  mutate that method, like any other edit to it, so it never reaches this
+  rule unless the method has nothing left to mutate.
 - **Exit 1** otherwise. A candidate file's code changed but produced no
-  mutants, and the warning lists the file(s). A deletion-only code edit
-  counts as a real change here.
+  mutants, and the warning lists the file(s).
 - With `--subject` and no `--since` there is no diff to judge, so
   `--allow-empty` exits `0` unconditionally.
 
@@ -301,6 +318,10 @@ projects used to tell a docs-only PR from a broken `--since` range.
 | `--require FILE` | none | preload files (repeatable) |
 | `--operator FILE` | none | load a custom operator file before analysis (repeatable) |
 | `--[no-]class-level` | on | mutate class-level code (macros, constants, DSL/scope lambdas) via class-body subjects |
+| `--diagnostics` | off | print timestamped phase, mutant, and memory lines to stderr, for finding out where a CI run died (see [Run diagnostics](docs/guides/diagnostics.md)) |
+| `--events FILE` | none | write the same events as NDJSON, one object per line, flushed as they happen |
+| `--sample-interval S` | 5 | seconds between memory samples with `--diagnostics`, `--events`, or `--max-rss` |
+| `--max-rss SIZE` | none | stop the run and exit 3 when the gem's total memory reaches SIZE (`6G`, `6144M`, or plain MB); warns once at 90% |
 | `--fail-at SCORE` | none (strict) | exit 0 if score >= SCORE even with survivors (opt-in relaxation for gradual adoption; 0 = report-only) |
 
 `--spec-path` tells active_mutator where spec files live (coverage
@@ -338,7 +359,10 @@ replaces the default `spec`),
 `adaptive_timeout` (`true`/`false`),
 `class_level` (`true`/`false`, default `true` — mutate class-level code),
 `class_level_closure_cap` (integer, default `10` — max constants a
-class-body mutant may reload before it is `skipped`).
+class-body mutant may reload before it is `skipped`),
+`diagnostics` (`true`/`false`, default `false`),
+`events_file` (a path), `sample_interval` (seconds, default `5`),
+`max_rss` (a size like `6G`, `6144M`, or plain MB).
 Unknown keys and wrong types are errors, not silent no-ops.
 
 ```yaml
@@ -425,6 +449,10 @@ remaining limits are:
 - [Operator reference](docs/guides/operators.md): every mutation
   active_mutator can generate, with before/after examples and what a
   survivor of each one means.
+- [Run diagnostics](docs/guides/diagnostics.md): `--diagnostics`,
+  `--events`, and `--max-rss`. Find the phase and mutants a dying CI run
+  was in, stop a run before it runs out of memory, and the `--events`
+  NDJSON schema.
 - [Custom operators](docs/guides/custom-operators.md): write and load your
   own mutation operators with `--operator` / the `operators:` config key.
 - [Mutation-check skill](docs/skills/mutation-check.md): the agent-facing

data/lib/active_mutator/abort_flag.rb

@@ -0,0 +1,53 @@
+module ActiveMutator
+  # A run stopped early by SIGINT, SIGTERM, or the memory ceiling. Carries
+  # what finished (`results`) and what was still running (`in_flight`).
+  class Aborted < StandardError
+    attr_reader :reason, :results, :in_flight
+
+    def initialize(reason, results: [], in_flight: [])
+      super("run aborted: #{reason}")
+      @reason = reason
+      @results = results
+      @in_flight = in_flight
+    end
+
+    # The same abort, with the finished results a caller up the stack knows.
+    def with_results(results) = self.class.new(reason, results: results, in_flight: in_flight)
+  end
+
+  # Where a signal or a memory breach lands. `trip!` is safe in a trap
+  # handler: no I/O and no locks (a Mutex in a trap raises ThreadError).
+  #
+  # Outside a `deferred` block, a trip raises Aborted on the main thread at
+  # once: boot and planning own no child processes, so there is nothing to
+  # clean up. Inside one (the baseline child's wait, the fork pool) it only
+  # records the reason; the owner's poll loop kills its children and then
+  # raises with what it knows. The first reason wins, and later trips are
+  # ignored while the abort is under way.
+  class AbortFlag
+    attr_reader :reason
+
+    def trip!(reason)
+      return if @reason
+
+      @reason = reason
+      Thread.main.raise(Aborted.new(reason)) unless @deferred
+    end
+
+    # Not an endless def: its one line runs at load, so coverage could
+    # never tie it to the specs that call it.
+    def tripped?
+      !@reason.nil?
+    end
+
+    def deferred
+      outer = @deferred
+      @deferred = true
+      raise Aborted, @reason if @reason
+
+      yield
+    ensure
+      @deferred = outer
+    end
+  end
+end

data/lib/active_mutator/baseline.rb

@@ -7,48 +7,69 @@ module ActiveMutator
   # caches the CoverageMap. Invalidation is coarse: any digest change in
   # {app,lib}/**/*.rb or the configured spec paths triggers a full re-run.
   class Baseline
-    def initialize(root:, spec_paths: ["spec"], cache_dir: File.join(root, ".active_mutator"))
+    def initialize(root:, spec_paths: ["spec"], cache_dir: File.join(root, ".active_mutator"), events: Events.new,
+                   abort: AbortFlag.new)
+      @abort = abort
       @root = root
       @spec_paths = spec_paths
       @cache_dir = cache_dir
       @out_path = File.join(cache_dir, "coverage.json")
+      @events = events
     end
 
-    attr_reader :last_refresh
+    POLL_SECONDS = 0.05
+
+    # child_pid: the running baseline child, nil between runs. Read by the
+    # memory sampler from its own thread.
+    attr_reader :last_refresh, :child_pid
 
     def coverage_map(force: false)
       digests = current_digests
-      if !force && File.exist?(@out_path)
-        map = CoverageMap.load(@out_path)
-        # A spec_paths change silently degrades the delta classifier: files
-        # under a removed spec path just vanish from the digest scan, so
-        # BaselineDelta treats their stale example records as untouched
-        # source coverage instead of dropping them. Force a full rebuild
-        # whenever the configured spec_paths differ from what the cache was
-        # stamped with.
-        if stored_spec_paths(map) == @spec_paths && map.fresh?(digests)
-          @last_refresh = :cached
-          return map
-        end
-        if stored_spec_paths(map) == @spec_paths && map.version == 2
-          delta = BaselineDelta.compute(old_digests: stored_digests(map), new_digests: digests,
-                                        coverage_map: map, root: @root, spec_paths: @spec_paths)
-          unless delta.full?
-            run_partial!(delta)
-            stamp_digests(digests)
-            @last_refresh = :partial
-            return CoverageMap.load(@out_path)
-          end
-        end
+      unless force
+        map = reuse_cache(digests)
+        return map if map
       end
-      run_baseline!
-      stamp_digests(digests)
+      data = run_baseline!
       @last_refresh = :full
-      CoverageMap.load(@out_path)
+      stamp(data, digests)
     end
 
     private
 
+    # The cached map, refreshed in place when a delta allows it; nil when only
+    # a full rebuild will do. The old map (records plus its inverted index)
+    # lives only in this method, so it is garbage before the full rebuild's
+    # child starts.
+    def reuse_cache(digests)
+      return unless File.exist?(@out_path)
+
+      data = load_payload
+      map = CoverageMap.new(data)
+      # A spec_paths change silently degrades the delta classifier: files
+      # under a removed spec path just vanish from the digest scan, so
+      # BaselineDelta treats their stale example records as untouched
+      # source coverage instead of dropping them. Force a full rebuild
+      # whenever the configured spec_paths differ from what the cache was
+      # stamped with.
+      return unless map.spec_paths == @spec_paths
+
+      if map.fresh?(digests)
+        @last_refresh = :cached
+        return map
+      end
+      return unless map.version == 2
+
+      delta = BaselineDelta.compute(old_digests: map.digests, new_digests: digests,
+                                    coverage_map: map, root: @root, spec_paths: @spec_paths)
+      return if delta.full?
+
+      # The map shares data["records"], and the merge edits it in place: the
+      # old map must not be read past this point.
+      run_partial!(delta, data)
+      @last_refresh = :partial
+      stamp(data, digests)
+    end
+
     # The cache is disposable and must never be committed. Host projects
     # rarely gitignore it themselves, so the directory ignores its own
     # contents (the node_modules trick).
@@ -60,22 +81,31 @@ module ActiveMutator
 
     def run_baseline!
       prepare_cache_dir
-      env = baseline_env(@out_path)
-      # out: :err: the subprocess suite's progress output must not pollute
-      # our stdout (breaks `--format json` consumers).
-      ok = system(env, "bundle", "exec", "rspec", chdir: @root, out: :err)
+      ok = run_rspec(@out_path)
       raise BaselineFailed, "baseline suite failed, fix the suite before mutating" unless ok
       raise BaselineFailed, "baseline produced no coverage output" unless File.exist?(@out_path)
 
-      verify_complete!(@out_path)
+      data = load_payload
+      verify_complete!(data)
+      data
+    end
+
+    # Its own phase, apart from the child's run: 0.6.0 died here, in the
+    # parent reading a huge file back. The size goes out BEFORE the parse, so
+    # the log names the cause even if nothing runs after it, and --max-rss
+    # can stop the run before the parse.
+    def load_payload(path = @out_path)
+      @events.emit(:phase_start, phase: :coverage_load, bytes: File.size(path))
+      data = JSON.parse(File.read(path))
+      @events.emit(:phase_end, phase: :coverage_load, examples: data.fetch("records", {}).size)
+      data
     end
 
     # An aborted subprocess can still exit 0 with a partial map (RSpec
     # rescues Errno::EPIPE and runs after(:suite)); stamping that as fresh
     # silently reports every mutant uncovered. Payloads without the count
     # predate this check and are accepted as-is.
-    def verify_complete!(out_path)
-      payload = JSON.parse(File.read(out_path))
+    def verify_complete!(payload)
       expected = payload["expected_examples"]
       return unless expected
 
@@ -87,6 +117,60 @@ module ActiveMutator
             "re-run without interrupting the suite"
     end
 
+    # Spawned and polled, not `system`, so the parent knows the child's pid
+    # and keeps control while it runs. out: :err: the subprocess suite's
+    # progress output must not pollute our stdout (breaks `--format json`
+    # consumers).
+    #
+    # The phase starts once the child exists, so it carries the pid the
+    # memory sampler follows. The child gets its own process group so an
+    # abort can kill the whole suite (browsers, app servers) in one signal;
+    # a Ctrl-C reaches it through the Runner's trap instead of the terminal.
+    # So does nothing else: a hangup from a closed terminal never reaches it,
+    # so anything that ends the wait early (an abort, SIGHUP, SIGQUIT) kills
+    # the group on the way out.
+    def run_rspec(out_path, targets = [])
+      status = nil
+      @abort.deferred do
+        @child_pid = Process.spawn(baseline_env(out_path), *rspec_command(targets), chdir: @root, out: :err,
+                                                                                    pgroup: true)
+        status = @events.phase(:baseline, refresh: targets.empty? ? :full : :partial, pid: @child_pid) do
+          wait_child(@child_pid)
+        end
+        # The memory sample taken as the phase ends can trip the ceiling.
+        # Stop here, before the coverage parse: that's the spike it guards.
+        raise Aborted, @abort.reason if @abort.tripped?
+
+        status.success?
+      end
+    rescue SystemCallError # `bundle` missing: `system` returned nil here
+      false
+    ensure
+      kill_group(@child_pid) if @child_pid && status.nil?
+      @child_pid = nil
+    end
+
+    def rspec_command(targets) = ["bundle", "exec", "rspec", *targets]
+
+    # The flag is checked after the wait, so a trip that lands as the child
+    # exits still stops the run here, not after the coverage parse.
+    # run_rspec kills the child's group on the way out.
+    def wait_child(pid)
+      loop do
+        _, status = Process.waitpid2(pid, Process::WNOHANG)
+        raise Aborted, @abort.reason if @abort.tripped?
+        return status if status
+
+        sleep POLL_SECONDS
+      end
+    end
+
+    def kill_group(pid)
+      Process.kill("KILL", -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil # already gone
+    end
+
     def baseline_env(out_path)
       {
         "ACTIVE_MUTATOR" => "1",
@@ -106,36 +190,25 @@ module ActiveMutator
       }
     end
 
-    def stored_digests(map)
-      JSON.parse(File.read(@out_path)).fetch("digests", {})
-    end
-
-    # A pre-0.4.0 cache predates spec_paths and has no key; treat that as the
-    # old implicit default so existing default-config caches stay valid.
-    def stored_spec_paths(map)
-      JSON.parse(File.read(@out_path)).fetch("spec_paths", ["spec"])
-    end
-
-    def run_partial!(delta)
-      targets = delta.rerun_spec_files + delta.rerun_example_ids
+    def run_partial!(delta, cache)
       partial_out = File.join(@cache_dir, "partial.json")
+      targets = delta.rerun_spec_files + delta.rerun_example_ids
+      part = {}
       if targets.any?
-        env = baseline_env(partial_out)
-        ok = system(env, "bundle", "exec", "rspec", *targets, chdir: @root, out: :err)
+        ok = run_rspec(partial_out, targets)
         raise BaselineFailed, "partial baseline run failed, fix the suite before mutating" unless ok
         raise BaselineFailed, "partial baseline produced no output" unless File.exist?(partial_out)
 
-        verify_complete!(partial_out)
+        part = load_payload(partial_out)
+        verify_complete!(part)
       end
-      merge_partial!(partial_out, delta)
+      merge_partial!(cache, part, delta)
     ensure
-      FileUtils.rm_f(partial_out) if partial_out
+      FileUtils.rm_f(partial_out)
     end
 
-    def merge_partial!(partial_out, delta)
-      cache = JSON.parse(File.read(@out_path))
-      part = File.exist?(partial_out) ? JSON.parse(File.read(partial_out)) : { "records" => {}, "times" => {} }
-
+    # Edits `cache` in place; the caller stamps and writes it.
+    def merge_partial!(cache, part, delta)
       rerun_prefixes = delta.rerun_spec_files.map { |rel| "#{rel}[" }
       obsolete = lambda do |example_id|
         bare = example_id.sub(%r{\A\./}, "")
@@ -151,14 +224,15 @@ module ActiveMutator
       end
       cache["records"].merge!(part.fetch("records", {}))
       cache["times"].merge!(part.fetch("times", {}))
-      AtomicFile.write(@out_path, JSON.generate(cache))
     end
 
-    def stamp_digests(digests)
-      data = JSON.parse(File.read(@out_path))
+    # Writes the stamped payload once and builds the map from the hash in
+    # hand, so the file is never parsed back.
+    def stamp(data, digests)
       data["digests"] = digests
       data["spec_paths"] = @spec_paths
       AtomicFile.write(@out_path, JSON.generate(data))
+      CoverageMap.new(data)
     end
 
     def current_digests

data/lib/active_mutator/cli.rb

@@ -32,7 +32,8 @@ module ActiveMutator
         spec_paths: ["spec"],
         browser_boot_seconds: 15.0, accept_survivors: false, exclude: [],
         max_mutants: nil, debug_plan: false, fail_at: nil, adaptive_timeout: true,
-        operators: [], class_level: true, class_level_closure_cap: 10, allow_empty: false
+        operators: [], class_level: true, class_level_closure_cap: 10, allow_empty: false,
+        diagnostics: false, events_file: nil, sample_interval: 5.0, max_rss: nil
       }
       options.merge!(ConfigFile.load(Dir.pwd))
       paths = OptionParser.new do |o|
@@ -69,6 +70,20 @@ module ActiveMutator
         o.on("--allow-empty",
              "Exit 0 when --since/--subject plan no mutants and the --since diff changed no code " \
              "in a mutable source file (default: exit 1)") { options[:allow_empty] = true }
+        o.on("--diagnostics", "Print phase, mutant, and memory lines to stderr") { options[:diagnostics] = true }
+        o.on("--events FILE", "Write run events to FILE as NDJSON, one object per line") { |v| options[:events_file] = v }
+        o.on("--sample-interval S", Float,
+             "Seconds between memory samples with --diagnostics, --events, or --max-rss (default: 5)") do |v|
+          raise OptionParser::InvalidArgument, "--sample-interval must be > 0" unless v.positive?
+          options[:sample_interval] = v
+        end
+        o.on("--max-rss SIZE", "Stop the run (exit 3) when the gem's total memory reaches SIZE: 6G, 6144M, " \
+                               "or MB; warns at 90%") do |v|
+          kb = MemoryCeiling.parse_kb(v)
+          raise OptionParser::InvalidArgument, "--max-rss takes a size like 6G, 6144M, or 6144 (MB)" unless kb
+
+          options[:max_rss] = kb
+        end
         o.on("--fail-at SCORE", Float, "Exit 0 if mutation score >= SCORE even with survivors (default: any survivor fails)") do |v|
           raise OptionParser::InvalidArgument, "--fail-at must be within 0..100" unless (0..100).cover?(v)
           options[:fail_at] = v

data/lib/active_mutator/config.rb

@@ -7,5 +7,12 @@ module ActiveMutator
                        :browser_boot_seconds,
                        :accept_survivors, :exclude, :max_mutants, :debug_plan,
                        :fail_at, :adaptive_timeout, :operators,
-                       :class_level, :class_level_closure_cap, :allow_empty)
+                       :class_level, :class_level_closure_cap, :allow_empty,
+                       :diagnostics, :events_file, :sample_interval, :max_rss) do
+    # Defaults for the 0.7.0 diagnostics fields, so a Config built by hand
+    # (specs, embedding hosts) doesn't have to name them. `max_rss` is in kB.
+    def initialize(diagnostics: false, events_file: nil, sample_interval: 5.0, max_rss: nil, **fields)
+      super
+    end
+  end
 end

data/lib/active_mutator/config_file.rb

@@ -26,7 +26,11 @@ module ActiveMutator
       "adaptive_timeout" => :boolean,
       "class_level" => :boolean,
       "class_level_closure_cap" => :positive_integer,
-      "allow_empty" => :boolean
+      "allow_empty" => :boolean,
+      "diagnostics" => :boolean,
+      "events_file" => :string,
+      "sample_interval" => :positive_number,
+      "max_rss" => :size
     }.freeze
 
     def self.load(root)
@@ -63,6 +67,10 @@ module ActiveMutator
       when :number
         raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
         value.to_f
+      when :positive_number
+        raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
+        raise Error, "#{FILENAME}: #{key} must be > 0" unless value.positive?
+        value.to_f
       when :score
         raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
         raise Error, "#{FILENAME}: #{key} must be within 0..100" unless (0..100).cover?(value)
@@ -72,6 +80,9 @@ module ActiveMutator
           raise Error, "#{FILENAME}: format must be one of #{FORMATS.join(", ")}"
         end
         value.tr("-", "_").to_sym
+      when :string
+        raise Error, "#{FILENAME}: #{key} must be a string" unless value.is_a?(String)
+        value
       when :string_list
         unless value.is_a?(Array) && value.all?(String)
           raise Error, "#{FILENAME}: #{key} must be a list of strings"
@@ -88,6 +99,11 @@ module ActiveMutator
           raise Error, "#{FILENAME}: #{key} must be true or false"
         end
         value
+      when :size
+        kb = MemoryCeiling.parse_kb(value)
+        raise Error, "#{FILENAME}: #{key} must be a size like 6G, 6144M, or 6144 (MB)" unless kb
+
+        kb
       when :preload_helper
         return :none if value == false
         raise Error, "#{FILENAME}: preload_helper must be a path or false" unless value.is_a?(String)

data/lib/active_mutator/coverage_map.rb

@@ -8,13 +8,16 @@ module ActiveMutator
   class CoverageMap
     def self.load(path) = new(JSON.parse(File.read(path)))
 
-    attr_reader :version, :records
+    attr_reader :version, :records, :digests, :spec_paths
 
     def initialize(data)
       @version = data["version"]
       @records = data.fetch("records", {})
       @times = data.fetch("times", {})
       @digests = data.fetch("digests", {})
+      # A pre-0.4.0 cache predates spec_paths and has no key; treat that as the
+      # old implicit default so existing default-config caches stay valid.
+      @spec_paths = data.fetch("spec_paths", ["spec"])
       @map = build_map
     end
 

data/lib/active_mutator/diagnostics/ndjson.rb

@@ -0,0 +1,25 @@
+require "json"
+
+module ActiveMutator
+  module Diagnostics
+    # --events FILE: every event as one JSON object per line. The public,
+    # versioned contract (docs/guides/diagnostics.md): new fields may appear
+    # under v1; a rename or removal bumps VERSION. The IO is sync, so each
+    # line reaches the OS as it's written and a SIGKILLed run still leaves
+    # everything up to the kill.
+    class Ndjson
+      VERSION = 1
+
+      def initialize(io)
+        @io = io
+        @io.sync = true
+      end
+
+      def call(event)
+        line = { "v" => VERSION, "event" => event.type.to_s,
+                 "t" => event.at.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "elapsed" => event.elapsed.round(3) }
+        @io.write("#{JSON.generate(line.merge(event.fields.transform_keys(&:to_s)))}\n")
+      end
+    end
+  end
+end

data/lib/active_mutator/diagnostics/text.rb

@@ -0,0 +1,110 @@
+module ActiveMutator
+  module Diagnostics
+    # Human sizes for diagnostic lines: 812M, 1.6G. nil (no reading) is "?".
+    def self.size_kb(kb)
+      return "?" unless kb
+      return "0" if kb.zero?
+      return format("%.1fG", kb / 1_048_576.0) if kb >= 1_048_576
+      return "#{(kb / 1024.0).round}M" if kb >= 1024
+
+      "#{kb}K"
+    end
+
+    # --diagnostics: one human-readable line per event, on stderr. stdout
+    # belongs to the reporter (`--format json` must stay parseable). `only`
+    # limits it to some event types.
+    class Text
+      def initialize(root:, out: $stderr, only: nil)
+        @prefix = "#{root.chomp("/")}/"
+        @out = out
+        @only = only
+      end
+
+      def call(event)
+        return if @only && !@only.include?(event.type)
+
+        stamp = "[active_mutator #{event.at.strftime("%H:%M:%S")} +#{format("%.1f", event.elapsed)}s]"
+        @out.puts "#{stamp} #{body(event.type, event.fields)}"
+      end
+
+      private
+
+      def body(type, fields)
+        case type
+        when :phase_start, :phase_end then phase(type, fields)
+        when :mutant_start then mutant_start(fields)
+        when :mutant_end then mutant_end(fields)
+        when :memory then memory(fields)
+        when :abort then abort(fields)
+        when :memory_warning then "warn #{ceiling(fields)}"
+        when :memory_ceiling then "#{ceiling(fields)}; stopping the run"
+        else [type, *pairs(fields)].join(" ")
+        end
+      end
+
+      def phase(type, fields)
+        edge = type == :phase_start ? "start" : "end"
+        ["phase", fields[:phase], edge, *pairs(fields.except(:phase))].join(" ")
+      end
+
+      def mutant_start(f)
+        "mutant start ##{f[:seq]} pid=#{f[:pid]} #{f[:lane]} #{f[:subject]} " \
+          "#{f[:file].delete_prefix(@prefix)}:#{f[:line]} #{f[:description]}"
+      end
+
+      def mutant_end(f)
+        "mutant end ##{f[:seq]} #{f[:status]} #{format("%.1f", f[:seconds])}s peak=#{Diagnostics.size_kb(f[:peak_rss_kb])}"
+      end
+
+      def abort(f)
+        running = f[:in_flight].map { |m| "##{m[:seq]} #{m[:subject]} #{m[:file].delete_prefix(@prefix)}:#{m[:line]}" }
+        "abort #{f[:reason]}; in flight: #{running.empty? ? "none" : running.join(", ")}"
+      end
+
+      # memory at 91% of --max-rss 6.0G (5.5G), or before a coverage parse:
+      # memory at 150% of --max-rss 6.0G (9.0G estimated to read a 1.7G coverage.json)
+      def ceiling(f)
+        percent = (f[:total_pss_kb] * 100.0 / f[:max_rss_kb]).round
+        total = Diagnostics.size_kb(f[:total_pss_kb])
+        if f[:coverage_bytes]
+          total += " estimated to read a #{Diagnostics.size_kb(f[:coverage_bytes] / 1024)} coverage.json"
+        end
+        "memory at #{percent}% of --max-rss #{Diagnostics.size_kb(f[:max_rss_kb])} (#{total})"
+      end
+
+      # mem parent=1.6G workers=4:3.2G baseline=2.1G total=6.9G avail=3.0G swap=0 psi=0.3 load=1.52
+      def memory(f)
+        parts = ["mem", "parent=#{size(f[:parent])}"]
+        parts << "workers=#{f[:workers].size}:#{Diagnostics.size_kb(f[:workers].sum { |w| kb(w) })}" if f[:workers].any?
+        parts << "baseline=#{size(f[:baseline])}" if f[:baseline]
+        parts << "total=#{Diagnostics.size_kb(f[:total_pss_kb])}"
+        parts.concat(system(f[:system])) if f[:system]
+        parts.join(" ")
+      end
+
+      def system(s)
+        parts = ["avail=#{Diagnostics.size_kb(s[:mem_available_kb])}"]
+        parts << "swap=#{Diagnostics.size_kb(s[:swap_total_kb] - s[:swap_free_kb])}" if s[:swap_total_kb] && s[:swap_free_kb]
+        parts << "psi=#{s[:psi_some_avg10]}" if s[:psi_some_avg10]
+        parts << "load=#{s[:load1]}" if s[:load1]
+        parts
+      end
+
+      # Not endless defs: a one-line method's line runs at
+      # load, so coverage can't tie it to the specs that call it.
+      def size(reading)
+        Diagnostics.size_kb(reading && kb(reading))
+      end
+
+      def kb(reading)
+        reading[:pss_kb] || reading[:rss_kb]
+      end
+
+      def pairs(fields)
+        fields.map do |key, value|
+          key == :bytes ? "size=#{Diagnostics.size_kb((value / 1024.0).round)}" : "#{key}=#{value}"
+        end
+      end
+    end
+  end
+end