mutineer 0.9.1 → 0.11.0

data/lib/mutineer/daemon_server.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+
+module Mutineer
+  # #26/#27 Phase 2a — the app-side daemon (persistent worker).
+  #
+  # Runs UNDER THE APP'S OWN BUNDLE/RUBY (the tool's DaemonClient spawns it via
+  # `bundle exec ruby`). It boots the app ONCE, then serves per-mutant test-run
+  # requests over stdin/stdout as newline-delimited JSON. For each request it FORKS
+  # a child that loads the mutated source text the tool sent, runs the covering
+  # tests, and exits with a status the parent decodes into a verdict.
+  #
+  # HARD CONSTRAINT (KTD-2/R4): this file must be loadable WITHOUT Prism or the rest
+  # of mutineer — the app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
+  # mutineer. So it requires ONLY stdlib + the app's own boot file; it re-implements
+  # the fork/timeout/decode loop rather than requiring `isolation.rb` (which pulls in
+  # Prism). All parsing/mutation happened tool-side; the daemon only `load`s text.
+  #
+  # Protocol (one JSON object per line, both directions):
+  #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment",
+  #               "load_paths":["test"],"framework":"minitest","rails":true,"schema":"db/schema.rb"}
+  #   ready out: {"ready":true,"ruby":"3.3.6"}   (or {"ready":false,"error":"..."} then exit)
+  #   run  in  : {"id":N,"worker":I,"payload":{"code":"<ruby>","source_file":"app/models/order.rb"},
+  #               "tests":["test/models/order_test.rb"],"timeout":30}
+  #   verdict  : {"id":N,"verdict":"survived"|"killed"|"error"|"timeout"}
+  #   quit in  : {"cmd":"quit"}
+  #
+  # Worker isolation (#26/U5): when the app is Rails, each fork is routed to its own
+  # database `<db>-<worker>` via {RailsWorkerDb} BEFORE any test loads, so concurrent
+  # workers can't clobber each other's transactional fixtures. `worker` defaults to 0
+  # (serial). SQLite this pass; Postgres provisioning is U10.
+  #
+  # Verdict mapping (KTD-5, Phase-2a honest limit): child exit 0=survived (suite
+  # passed), 1=killed (suite failed), 2=error (child raised AROUND the test — load,
+  # boot, or worker-DB routing failure); parent-detected timeout. Tagging an in-TEST DB
+  # error (one fired inside a test body, vs at routing time) as `error` rather than
+  # `killed` is a U6 concern — only observable under the concurrent gate.
+  module DaemonServer
+    # Poll interval (seconds) for the per-fork deadline wait loop.
+    POLL = 0.02
+
+    class << self
+      # Serve the protocol on the given IO pair (defaults to stdio). Returns on quit.
+      #
+      # @param input [IO] request stream.
+      # @param output [IO] verdict stream.
+      # @param errio [IO] diagnostics stream (never the IPC channel).
+      # @return [void]
+      def run(input: $stdin, output: $stdout, errio: $stderr)
+        @errio = errio
+        @output = output
+        boot_line = input.gets
+        return if boot_line.nil? # client vanished before boot
+
+        boot!(JSON.parse(boot_line.strip))
+        output.puts(JSON.generate("ready" => true, "ruby" => RUBY_VERSION))
+        output.flush
+
+        input.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          begin
+            req = JSON.parse(line)
+          rescue JSON::ParserError => e
+            # A corrupt line has no id to address a reply to (and the client only ever
+            # sends valid JSON, so it can't be a pending request) — log and read on
+            # rather than write an unaddressable verdict onto the channel.
+            @errio.puts("[daemon] dropped unparseable line: #{e.message}")
+            next
+          end
+          break if req["cmd"] == "quit"
+
+          # #26/U7: build the coverage map app-side and ship it to the tool, which
+          # then selects covering tests per mutant. One-shot control message.
+          if req["cmd"] == "coverage"
+            output.puts(JSON.generate(build_coverage_map))
+            output.flush
+            next
+          end
+
+          output.puts(JSON.generate(run_mutant(req)))
+          output.flush
+        end
+      end
+
+      private
+
+      # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded and
+      # inherited by every fork. Never requires mutineer.
+      def boot!(cfg)
+        @cfg = cfg
+        @framework = cfg.fetch("framework", "minitest")
+        @source_dirs = Array(cfg["source_dirs"]).map { |d| File.expand_path(d) }
+        Dir.chdir(cfg["project_root"]) if cfg["project_root"]
+        ENV["RAILS_ENV"] ||= "test" if cfg["rails"]
+        Array(cfg["load_paths"]).each { |d| $LOAD_PATH.unshift(File.expand_path(d)) }
+        # #26/U7: start Coverage BEFORE the app loads, so booted source lines are
+        # instrumented — the map build (build_via_fork) forks this booted parent.
+        if cfg["coverage"]
+          require "coverage"
+          Coverage.start(lines: true)
+        end
+        # Clear any mutant tempfile a prior SIGKILLed timeout child orphaned in a
+        # source dir BEFORE the app boots — Zeitwerk would otherwise choke on the
+        # tempfile's non-constant name during autoload setup.
+        sweep_temps
+        require File.expand_path(cfg["boot"]) if cfg["boot"]
+        setup_worker_db(cfg) if cfg["rails"]
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Boot failed (bad boot path, app error) — tell the client and exit so it can
+        # surface a clean error rather than hang on the handshake.
+        @output.puts(JSON.generate("ready" => false, "error" => "#{e.class}: #{e.message}"))
+        @output.flush
+        exit!(1)
+      end
+
+      # Load the per-worker DB adapter app-side (sibling gem file, by relative path so
+      # it bypasses the app bundle — like this daemon itself). No-op unless the app has
+      # ActiveRecord. Records the adapter + schema path so each fork can route to its
+      # own database (#26 isolation, U5). SQLite-only this pass; a non-SQLite config
+      # raises in the fork and reads as `error`, never a mis-routed verdict.
+      def setup_worker_db(cfg)
+        require_relative "rails_worker_db"
+        @worker_db = RailsWorkerDb.available? ? RailsWorkerDb : nil
+        schema = cfg["schema"] && File.expand_path(cfg["schema"])
+        @schema_path = schema if schema && File.exist?(schema)
+      rescue LoadError => e
+        @errio.puts("[daemon] worker-DB routing unavailable: #{e.message}")
+        @worker_db = nil
+      end
+
+      # #26/U7: build the coverage map app-side (Coverage was started at boot) and
+      # return it as `{map, failed_test_files}` for the tool to select covering tests.
+      # Capture forks route to worker 0's DB (isolated, serial). On any failure return
+      # an empty map + an error string — the tool then falls back to the full test set
+      # rather than mis-scoring everything as no_coverage.
+      def build_coverage_map
+        require_relative "coverage_map"
+        root = @cfg["project_root"] || Dir.pwd
+        cmap = CoverageMap.new(
+          source_paths: Array(@cfg["sources"]), test_paths: Array(@cfg["tests"]),
+          load_paths: Array(@cfg["load_paths"]), project_root: root,
+          boot_path: @cfg["boot"], framework: @framework, cache_dir: File.join(root, ".mutineer")
+        ).build_via_fork(after_fork: coverage_after_fork)
+        { "map" => cmap.map, "failed_test_files" => cmap.failed_test_files }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        @errio.puts("[daemon] coverage build failed: #{e.class}: #{e.message}")
+        { "map" => {}, "failed_test_files" => [], "error" => "#{e.class}: #{e.message}" }
+      end
+
+      # Fork-safety hook for coverage capture: route each capture fork to worker 0's
+      # isolated DB (captures run serially, so one worker is enough). Nil when the app
+      # has no worker-DB adapter (non-Rails) — capture then runs as before.
+      def coverage_after_fork
+        return nil unless @worker_db
+
+        schema = @schema_path
+        -> { @worker_db.after_fork(0, schema) }
+      end
+
+      # Fork a child to run one mutant in isolation; decode its exit into a verdict.
+      def run_mutant(req)
+        timeout = req.fetch("timeout", 30)
+        worker  = req.fetch("worker", 0)
+        pid = fork do
+          # New process group so a per-fork timeout can SIGKILL the whole subtree
+          # (carries the Phase-1 pgroup discipline), and silence the child's stdout so
+          # test-framework output can never corrupt the IPC pipe (KTD-6).
+          Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
+          $stdout.reopen(File::NULL, "w")
+          code =
+            begin
+              # Route THIS fork at its own worker database before any test loads, so
+              # concurrent workers can't clobber each other's fixtures (#26). A routing
+              # failure raises here and is scored `error` below, never a false verdict.
+              @worker_db&.after_fork(worker, @schema_path)
+              apply_payload(req["payload"])
+              run_tests(Array(req["tests"]))
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              @errio.puts("[daemon-child] #{e.class}: #{e.message}")
+              2
+            end
+          exit!(code)
+        end
+        verdict = wait_verdict(pid, timeout)
+        # A SIGKILLed timeout child skipped its Tempfile unlink — sweep the orphan so
+        # it can't outlive the run or trip Zeitwerk on a later fork.
+        sweep_temps if verdict == "timeout"
+        { "id" => req["id"], "verdict" => verdict }
+      end
+
+      # Remove orphaned mutant tempfiles from the source dirs (parent-side; the
+      # SIGKILL path can't run the child's ensure). Mirrors Runner.sweep_orphans.
+      def sweep_temps
+        @source_dirs.to_a.each do |dir|
+          Dir.glob(File.join(dir, "mutineer_daemon*.rb")).each do |f|
+            File.unlink(f) rescue nil # rubocop:disable Style/RescueModifier
+          end
+        end
+      end
+
+      # Single-waiter deadline loop (mirrors Isolation.run and
+      # ExternalBackend.wait_with_timeout, re-implemented here because Isolation pulls
+      # in Prism which is forbidden app-side). NOTE: this is the 3rd copy of the
+      # waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline — a fix to the
+      # kill/reap/decode logic must be applied to all three in lockstep. SIGKILL the
+      # child's process group past the deadline; a signalled child (nil exitstatus) is
+      # `error`.
+      def wait_verdict(pid, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          reaped, status = Process.waitpid2(pid, Process::WNOHANG)
+          if reaped
+            return { 0 => "survived", 1 => "killed" }.fetch(status.exitstatus, "error")
+          end
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            begin
+              Process.kill(:KILL, -pid)
+            rescue Errno::ESRCH, Errno::EPERM
+              Process.kill(:KILL, pid) rescue nil # rubocop:disable Style/RescueModifier
+            end
+            Process.waitpid(pid) rescue nil # rubocop:disable Style/RescueModifier
+            return "timeout"
+          end
+          sleep POLL
+        end
+      end
+
+      # Write the tool-built mutated text beside the real source and `load` it —
+      # reopening the mutated class/method in THIS child only. It goes in the source
+      # file's directory (like Isolation.apply_whole_file) so a `require_relative` in
+      # the mutated source resolves against its real neighbours — writing it to the
+      # tmpdir would LoadError on such files and score a spurious `error` that
+      # diverges from the in-process path. The Zeitwerk hazard (a stray `.rb` in an
+      # autoload dir) is handled by the boot/timeout `sweep_temps`, not by relocating
+      # the file. Same path for reload (whole file) and redefine (wrapped snippet).
+      def apply_payload(payload)
+        dir = File.dirname(File.expand_path(payload.fetch("source_file")))
+        Tempfile.create(["mutineer_daemon", ".rb"], dir) do |f|
+          f.write(payload.fetch("code"))
+          f.flush
+          load f.path
+        end
+      end
+
+      # Load the covering test files and run them; 0 = all passed (survived),
+      # 1 = a failure/error (killed). Minitest only in 2a (rspec is a later unit).
+      def run_tests(tests)
+        raise "unsupported framework #{@framework.inspect}" unless @framework == "minitest"
+
+        require "minitest"
+        require "rails/test_help" if defined?(Rails)
+        tests.each { |t| load File.expand_path(t) }
+        Minitest.run([]) ? 0 : 1
+      end
+    end
+  end
+end

data/lib/mutineer/external_backend.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "tempfile"
+require_relative "result"
+
+module Mutineer
+  # Raised when the smoke check (the unmutated suite) is not green, so the run
+  # aborts before scoring — a broken environment must never be reported as strong
+  # tests. The CLI maps this to a runtime error (exit 1), not a usage error.
+  class SmokeCheckError < StandardError; end
+
+  # #27 (U3): the external execution backend. Runs the user's `--test-command` as a
+  # subprocess in the app's OWN runtime (whatever Ruby its bundle resolves to), so
+  # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
+  #
+  # This is deliberately NOT a `TestRunners` framework adapter: those return an
+  # Integer 0/1 from inside a fork and are dispatched by framework name. This is a
+  # whole backend — it spawns a process, enforces a wall-clock timeout, and maps
+  # the exit status to a Result. The mapping is the SAME direction as in-process
+  # (suite passes => survived, suite fails => killed) but coarser: it cannot tell an
+  # infrastructure error from a genuine kill, so the smoke check (below) guards the
+  # persistent case and the score is disclosed as an upper bound (KTD-3/KTD-6).
+  module ExternalBackend
+    # Generous ceiling for the one-off smoke/calibration run (a cold app boot plus
+    # the full suite). The per-mutant timeout is derived from how long this took.
+    SMOKE_TIMEOUT = 900
+    # Poll interval for the deadline wait loop. Independent of Isolation's loop —
+    # this backend waits on an external process TREE, not an in-process fork.
+    POLL = 0.02
+
+    # Turn a command template into an argv array (no shell → no eval, no
+    # injection). The `%{files}` token expands IN PLACE to N separate argv
+    # elements — one per path, unescaped — so a path containing a space stays a
+    # single argument. It is not a space-joined string.
+    #
+    # @param command [String] the --test-command template (contains %{files}).
+    # @param files [Array<String>] test file paths to substitute.
+    # @return [Array<String>] argv.
+    def self.build_argv(command, files)
+      Shellwords.split(command).flat_map { |tok| tok == "%{files}" ? files : [tok] }
+    end
+
+    # Runs the command for ONE mutant against whatever is currently on disk (the
+    # caller has already swapped the mutant in via FileSwap). Maps the outcome to a
+    # Result. Env is inherited by the subprocess, so `RAILS_ENV=test mutineer …`
+    # reaches the child with no parsing here.
+    #
+    # @param command [String] the --test-command template.
+    # @param files [Array<String>] test file paths.
+    # @param timeout [Numeric] per-mutant wall-clock timeout in seconds.
+    # @param verbose [Boolean] print the child's captured output on a non-pass.
+    # @return [Mutineer::Result]
+    def self.run(command, files, timeout:, verbose: false)
+      kind, code, output, = spawn_capture(command, files, timeout)
+      case kind
+      when :timeout
+        # A timeout is the one non-pass we flag by default — a normal kill is also
+        # a non-zero exit, so notifying on every non-zero would spam every kill.
+        warn "[mutineer] test-command exceeded #{timeout}s and was killed (scored timeout)."
+        warn output if verbose && !output.empty?
+        Result.timeout
+      else # :exited
+        return Result.survived if code&.zero?
+
+        warn output if verbose && !output.empty?
+        Result.killed
+      end
+    end
+
+    # Pre-flight: run the command once against the UNMUTATED tree. Green (exit 0)
+    # returns the elapsed seconds (used to calibrate the per-mutant timeout);
+    # anything else raises SmokeCheckError so the run aborts before scoring.
+    #
+    # @param command [String] the --test-command template.
+    # @param files [Array<String>] test file paths.
+    # @param timeout [Numeric] ceiling for the calibration run.
+    # @return [Float] elapsed seconds of the clean run.
+    # @raise [Mutineer::SmokeCheckError] when the clean suite is not green.
+    def self.smoke_check!(command, files, timeout: SMOKE_TIMEOUT)
+      kind, code, output, elapsed = spawn_capture(command, files, timeout)
+      return elapsed if kind == :exited && code&.zero?
+
+      reason =
+        if kind == :timeout then "did not finish within #{timeout}s"
+        elsif code.nil?      then "was terminated by a signal"
+        else                      "exited #{code}"
+        end
+      detail = output.empty? ? "" : "\n--- last output ---\n#{tail(output)}"
+      raise SmokeCheckError,
+            "the test command #{reason} against the UNMUTATED source — the " \
+            "environment looks broken (check DB, RAILS_ENV, migrations), not the " \
+            "tests weak.#{detail}"
+    end
+
+    # Spawns the command to a captured combined-output tempfile, enforces a
+    # wall-clock timeout (SIGKILL past the deadline), and returns
+    # [kind, exit_code, output, elapsed]. Mirrors Isolation's single-waiter loop:
+    # we are the only caller of waitpid on this pid, so the kill can never hit a
+    # reaped/recycled pid.
+    #
+    # @api private
+    def self.spawn_capture(command, files, timeout)
+      argv = build_argv(command, files)
+      # Unreachable in practice (validate_test_command! guarantees a non-empty
+      # command with %{files}); a neutral ArgumentError, not the smoke-specific
+      # SmokeCheckError, since this is not a smoke-check failure.
+      raise ArgumentError, "--test-command produced an empty command" if argv.empty?
+
+      out = Tempfile.create("mutineer_ext")
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      # `pgroup: true` puts the child in its OWN process group so a timeout can
+      # kill the whole tree (`bundle exec rails test` forks parallel workers;
+      # spring/bundler add more) — killing only the leader would orphan workers
+      # that keep holding the shared DB, corrupting later serial mutants. The
+      # explicit [program, argv0] form guarantees the no-shell exec path even for a
+      # degenerate single-element argv (Process.spawn(*argv) would route a lone
+      # metachar-bearing string through /bin/sh, breaking the argv-only invariant).
+      pid = Process.spawn([argv.first, argv.first], *argv[1..], out: out, err: %i[child out], pgroup: true)
+      kind, code = wait_with_timeout(pid, timeout)
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      out.rewind
+      [kind, code, out.read, elapsed]
+    ensure
+      if out
+        out.close
+        File.unlink(out.path) rescue nil # rubocop:disable Style/RescueModifier
+      end
+    end
+
+    # Waits for the spawned pid, SIGKILLing its process group past the deadline.
+    # Single-waiter deadline loop (mirrors Isolation), so the kill can never hit a
+    # reaped/recycled pid.
+    #
+    # @api private
+    # @param pid [Integer] the spawned child pid.
+    # @param timeout [Numeric] wall-clock deadline in seconds.
+    # @return [Array(Symbol, Integer, nil)] `[:exited, code]` or `[:timeout, nil]`.
+    def self.wait_with_timeout(pid, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        reaped, status = Process.waitpid2(pid, Process::WNOHANG)
+        return [:exited, status.exitstatus] if reaped
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          # Kill the whole process GROUP (negative pid) so forked test workers die
+          # with the leader; fall back to the leader alone if the group is already
+          # gone. The child led its group (pgroup: true at spawn).
+          begin
+            Process.kill(:KILL, -pid)
+          rescue Errno::ESRCH, Errno::EPERM
+            Process.kill(:KILL, pid) rescue nil # rubocop:disable Style/RescueModifier
+          end
+          Process.waitpid(pid) rescue nil # rubocop:disable Style/RescueModifier
+          return [:timeout, nil]
+        end
+        sleep POLL
+      end
+    end
+
+    # Last ~40 lines of captured output, for a smoke-failure message.
+    #
+    # @api private
+    def self.tail(output, lines = 40)
+      output.lines.last(lines).join
+    end
+  end
+end

data/lib/mutineer/file_swap.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Raised when a source file's backup already exists as FileSwap.with begins —
+  # a second mutineer run is racing on the same file (the backup path is shared
+  # and unlocked). Aborting beats silently leaving the tree mutated.
+  class ConcurrentRunError < StandardError
+    def initialize(backup)
+      super("a backup already exists at #{backup} — is another mutineer run active " \
+            "in this directory? Aborting to avoid corrupting the source file.")
+    end
+  end
+
+  # #27 (U2): apply one whole-file mutant to the REAL source path for the external
+  # (`--test-command`) backend, and guarantee the original is restored on every
+  # exit path. A separate `bundle exec` subprocess has its own VM and cannot see an
+  # in-process `load`, so the mutant must live on disk while its suite runs — which
+  # makes leaving the file mutated the one genuinely dangerous failure mode.
+  #
+  # Defense in depth, mirroring the tempfile-orphan discipline
+  # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
+  #   - the original bytes are held in memory AND written to a sibling backup;
+  #   - `ensure` restores from memory around every mutant;
+  #   - the backup survives a SIGKILL (which skips `ensure`), so `restore_orphans`
+  #     can self-heal a left-mutated tree on the next run's startup.
+  # Only one mutant is in flight per file at a time (the external path is serial),
+  # so backups never collide.
+  module FileSwap
+    # Suffix for the on-disk backup; fixed so `restore_orphans` finds it.
+    BACKUP_SUFFIX = ".mutineer-backup"
+
+    # Writes `mutated` to `source_file`, yields, then restores the original bytes
+    # on every exit path (normal return, exception, or `ensure`). Byte-exact:
+    # binary read/write preserves encoding, newlines, and trailing bytes.
+    #
+    # @param source_file [String] path to the real source file.
+    # @param mutated [String] mutated source text to write for the duration.
+    # @yield the block to run while the mutant is on disk.
+    # @return [Object] the block's return value.
+    def self.with(source_file, mutated)
+      backup = source_file + BACKUP_SUFFIX
+      # A backup already on disk means either a prior hard-killed run (restore_orphans
+      # should have healed it at startup) or a SECOND mutineer run racing us on the
+      # same file. The backup path is shared and unlocked, so proceeding would let
+      # us capture the other run's mutant AS the "original" and permanently mutate
+      # the tree. Refuse loudly rather than silently corrupt — and do it BEFORE
+      # `created` is set, so the ensure below never touches a backup we don't own.
+      raise ConcurrentRunError, backup if File.exist?(backup)
+
+      original = File.binread(source_file)
+      File.binwrite(backup, original)
+      created = true
+      File.binwrite(source_file, mutated)
+      yield
+    ensure
+      if created
+        File.binwrite(source_file, original)
+        File.unlink(backup) if File.exist?(backup)
+      end
+    end
+
+    # Startup/after-run self-heal: restore any source file left mutated by a prior
+    # interrupted run (a leftover `*.mutineer-backup`), then remove the backup.
+    # Prints one line to stderr when it actually heals something, so a developer
+    # knows their working tree was auto-restored (a file they did not touch).
+    #
+    # @param dirs [Array<String>] directories to sweep for orphaned backups.
+    # @return [void]
+    def self.restore_orphans(dirs)
+      healed = 0
+      dirs.uniq.each do |dir|
+        Dir.glob(File.join(dir, "*#{BACKUP_SUFFIX}")).each do |backup|
+          source_file = backup.delete_suffix(BACKUP_SUFFIX)
+          backup_bytes = File.binread(backup)
+          if !File.exist?(source_file)
+            # A real user file that merely ends in our suffix, with no sibling to
+            # restore — leave it untouched (never create a file from it).
+            next
+          elsif File.binread(source_file) == backup_bytes
+            # Redundant backup (e.g. a crash between restore and unlink): nothing to
+            # heal, just clear the orphan so the next run doesn't see a false race.
+            File.unlink(backup)
+          else
+            File.binwrite(source_file, backup_bytes)
+            File.unlink(backup)
+            healed += 1
+          end
+        end
+      end
+      return if healed.zero?
+
+      warn "[mutineer] restored #{healed} source file(s) left mutated by a previous interrupted run."
+    end
+  end
+end