mutineer 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9104fa94a852cbd1257f9dce0af285865d98da1100849f5d1b8c5af12d6513fa
-  data.tar.gz: 4ca6421fdd7ef6ef862813cbd74481ec6babf176991c8d34301368861ea19272
+  metadata.gz: a96e7bad1e1cf8d106957e770418e6a1854c677943114b9bc45421c4e06da7f2
+  data.tar.gz: c404d87071f3d270566e368ac70153f1e87c940eb170b220b972fb1b28b29889
 SHA512:
-  metadata.gz: 66a7b0eae5bb41331d267b4c26a0b72e9023177d89d9d21cc679e712978836c4884b8b0347fd8263f55041897c2581e7117d5ae522965efbdb9af0daf5b47fee
-  data.tar.gz: cf1ed699c65b733b717ce5ed6ee95f9f50387fb2963b0ecd5516fa43d6a18bd21e0c354f2c85bde2df56cec305446cd988697f8eb5ae5b080bdfd9d2edc0fa06
+  metadata.gz: 15417ab5322c43c537953eaa438c18a9a89794f199a9c4666f031daf60f55f6c3ffabcb2e69e15b7ffd030e48b6f2d5d3ab41ee01ccfe9d52dd6c9ee22b4971c
+  data.tar.gz: 1e68e920b3aa610ea1715c16e48e89060e8eba2b2511aafb3c7db0c44e21f8fac077529173befd9acf3afbe2962829cf4534dce371a2f6262628dd507f37469b

data/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-18
+
+### Added
+- **RubyGems `documentation_uri`**: the published gem now points at the docs
+  site (`https://davidteren.github.io/mutineer/`) so gem-page discovery
+  reaches the Pages docs (#90).
+
+### Fixed
+- **A red unmutated suite can no longer pass a mutation gate** — coverage
+  capture now keeps the original Minitest/RSpec result, and a failing clean run
+  aborts with the existing smoke-check error (exit 1) instead of scoring those
+  assertion failures as killed mutants. A warm coverage cache re-checks the
+  current suite and cannot bypass this (#96).
+- **Concurrent external runs no longer restore each other's source files** —
+  swap and orphan recovery share one exclusive OS lock per source, acquired
+  before reading or healing. A live owner's mutant and backup stay intact; a
+  dead owner's backup still restores the original bytes (#99).
+- **Coverage cache now invalidates when a required test helper changes** —
+  a successful map records fingerprints of project-local loaded Ruby files,
+  old cache entries without that data rebuild, and a helper-only edit no
+  longer hides a new survivor behind a stale 100% score (#97).
+- **Release version calculation ignores floating major tags** — `release-pr.yml`
+  selects the newest complete `vMAJOR.MINOR.PATCH` ancestor and validates the
+  next version before writing files, so a later `v1` tag can no longer produce
+  `v1..1` (#95).
+
 ## [1.0.0] - 2026-09-08
 
 The GitHub Action's PR default changes in this release, which is why it is a
@@ -381,6 +407,7 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[1.0.1]: https://github.com/davidteren/mutineer/releases/tag/v1.0.1
 [1.0.0]: https://github.com/davidteren/mutineer/releases/tag/v1.0.0
 [0.11.4]: https://github.com/davidteren/mutineer/releases/tag/v0.11.4
 [0.11.3]: https://github.com/davidteren/mutineer/releases/tag/v0.11.3

data/lib/mutineer/cli.rb

@@ -218,6 +218,11 @@ module Mutineer
       # environment, not weak tests. Runtime error (exit 1), not usage (exit 2).
       warn "mutineer: #{e.message}"
       exit 1
+    rescue Mutineer::ConcurrentRunError => e
+      # Another process owns a source file. Runtime error (exit 1), not a
+      # backtrace: the working tree is still the other run's responsibility.
+      warn "mutineer: #{e.message}"
+      exit 1
     rescue Mutineer::DaemonBootError => e
       # The daemon is gone for good, so the run ended rather than scoring the rest
       # against it. A deliberate stop deserves a message, not a raw backtrace.

data/lib/mutineer/coverage_map.rb

@@ -22,7 +22,7 @@ module Mutineer
     # Seconds per coverage subprocess before the parent kills it.
     DEFAULT_CAPTURE_TIMEOUT = 120
 
-    attr_reader :project_root, :failed_test_files, :phase_a_ran, :map
+    attr_reader :project_root, :failed_test_files, :failed_clean_tests, :phase_a_ran, :map
 
     # Build a QUERY-ONLY map from data captured elsewhere (the daemon builds the
     # map app-side and ships `map` + `failed_test_files` over IPC; the tool
@@ -33,11 +33,13 @@ module Mutineer
     # @param map [Hash] the "file:line" => [test_files] map.
     # @param failed_test_files [Array<String>] test files whose capture failed.
     # @param project_root [String] project root (for path relativization).
+    # @param failed_clean_tests [Array<String>] test files whose unmutated run failed.
     # @return [Mutineer::CoverageMap] a query-only map.
-    def self.from_data(map:, failed_test_files:, project_root:)
+    def self.from_data(map:, failed_test_files:, project_root:, failed_clean_tests: [])
       instance = allocate
       instance.instance_variable_set(:@map, map || {})
       instance.instance_variable_set(:@failed_test_files, failed_test_files || [])
+      instance.instance_variable_set(:@failed_clean_tests, failed_clean_tests || [])
       instance.instance_variable_set(:@project_root, project_root)
       instance
     end
@@ -57,6 +59,8 @@ module Mutineer
       @verbose      = verbose
       @map          = {}
       @failed_test_files = []
+      @failed_clean_tests = []
+      @loaded_dependencies = {}
       @phase_a_ran  = false
     end
 
@@ -75,7 +79,7 @@ module Mutineer
     # never collides with a standalone one).
     def build_via_fork(after_fork: nil)
       warn_external_sources
-      cached_or { run_phase_a_via_fork(after_fork: after_fork) }
+      cached_or(after_fork: after_fork) { run_phase_a_via_fork(after_fork: after_fork) }
     end
 
     # Lookup: the test files that cover `file:line`, or [] when none do.
@@ -141,18 +145,30 @@ module Mutineer
     end
 
     # Shared cache dance for both build paths: hit the digest-keyed cache, else
-    # yield to populate @map and persist it.
-    def cached_or
+    # yield to populate @map and persist it. A digest match is not proof that
+    # today's unmutated suite still passes — re-check on a cache hit.
+    #
+    # @param after_fork [Proc, nil] boot-mode fork hook forwarded to a clean re-check.
+    # @yield when the cache is missing or stale.
+    # @return [Mutineer::CoverageMap] self.
+    def cached_or(after_fork: nil)
       @digest = compute_digest
       cached = read_cache
-      if cached && cached["digest"] == @digest
+      if cached && cached["digest"] == @digest && dependencies_match?(cached)
         @map = cached["map"] || {}
         @failed_test_files = cached["failed_test_files"] || []
+        @failed_clean_tests = []
+        @loaded_dependencies = cached["dependencies"] || {}
+        retry_failed_captures(after_fork)
         warn_incomplete unless @failed_test_files.empty?
+        verify_cached_clean(after_fork: after_fork)
+        verify_combined_clean(after_fork: after_fork)
+        save
         return self
       end
 
       yield
+      verify_combined_clean(after_fork: after_fork)
       save
       self
     end
@@ -164,12 +180,14 @@ module Mutineer
       @phase_a_ran = true
       @map = {}
       @failed_test_files = []
+      @failed_clean_tests = []
+      @loaded_dependencies = {}
 
       @test_paths.each do |test_path|
-        coverage = capture(test_path)
-        next unless coverage
+        payload = capture(test_path)
+        next unless payload
 
-        record(coverage, test_path)
+        accept_capture_payload(test_path, payload)
       end
     end
 
@@ -182,16 +200,18 @@ module Mutineer
       @phase_a_ran = true
       @map = {}
       @failed_test_files = []
+      @failed_clean_tests = []
+      @loaded_dependencies = {}
       abs_sources = abs_source_paths
 
       @test_paths.each do |test_path|
-        # Tri-state payload: Hash = coverage, String = error diagnostic from the
-        # child, nil = pipe gone / empty. The String diagnostic is what becomes
-        # an :uncapturable status.
-        case (coverage = fork_capture(absolute(test_path), abs_sources, after_fork))
-        when Hash   then record(coverage, test_path)
+        # Tri-state payload: Hash = capture result, String = error diagnostic from
+        # the child, nil = pipe gone / empty. The String diagnostic is what
+        # becomes an :uncapturable status.
+        case (payload = fork_capture(absolute(test_path), abs_sources, after_fork))
+        when Hash then accept_capture_payload(test_path, payload)
         when String
-          fail_test(test_path, @verbose ? "fork capture failed: #{coverage}" :
+          fail_test(test_path, @verbose ? "fork capture failed: #{payload}" :
             "fork capture produced no result (re-run with --verbose for the error)")
         else fail_test(test_path, "fork capture produced no result")
         end
@@ -217,12 +237,14 @@ module Mutineer
             # file needs neither Runner (Prism) nor Rails.
             after_fork&.call
             Coverage.result(clear: true, stop: false) # discard pre-test delta
-            TestRunners.for(@framework).run([abs_test])
+            passed = TestRunners.for(@framework).run([abs_test]).zero?
             # lines:true yields {file => {lines: [...]}}; reduce to the counts
             # array record() expects, keeping only our source files.
-            Coverage.result(stop: false)
-                    .select { |f, _| abs_sources.include?(f) }
-                    .transform_values { |v| v.is_a?(Hash) ? v[:lines] : v }
+            coverage = Coverage.result(stop: false)
+                               .select { |f, _| abs_sources.include?(f) }
+                               .transform_values { |v| v.is_a?(Hash) ? v[:lines] : v }
+            { "passed" => passed, "coverage" => coverage,
+              "loaded_files" => capture_loaded_files }
           rescue Exception => e # rubocop:disable Lint/RescueException
             # Stringify (an arbitrary Exception may not marshal); the parent
             # surfaces this under --verbose. A String marshals safely over the pipe.
@@ -268,8 +290,8 @@ module Mutineer
 
     # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
     # miss already-loaded app lines, so Coverage must start in a clean process
-    # before any source is loaded. Returns the parsed Coverage.result hash, or
-    # nil when the subprocess failed (logged + skipped).
+    # before any source is loaded. Returns the wrapped capture payload
+    # (`passed` + `coverage`), or nil when the subprocess failed (logged + skipped).
     def capture(test_path)
       out = +""
       status = nil
@@ -289,7 +311,10 @@ module Mutineer
       end
       return fail_test(test_path, "subprocess exited #{status.exitstatus}") unless status.success?
 
-      JSON.parse(out)
+      parsed = JSON.parse(out)
+      return fail_test(test_path, "invalid coverage output: missing pass/coverage payload") unless wrapped_capture?(parsed)
+
+      parsed
     rescue JSON::ParserError => e
       fail_test(test_path, "invalid coverage output: #{e.message}")
     end
@@ -307,6 +332,241 @@ module Mutineer
       nil
     end
 
+    # True when `payload` is the wrapped capture JSON/Marshal contract
+    # (`passed` + `coverage`), not a raw Coverage.result hash.
+    #
+    # @api private
+    # @param payload [Object] parsed subprocess output or forked Marshal value.
+    # @return [Boolean]
+    def wrapped_capture?(payload)
+      payload.is_a?(Hash) && payload.key?("passed") && payload.key?("coverage")
+    end
+
+    # Records a wrapped capture: assertion failures go to {#failed_clean_tests};
+    # successful coverage is inverted into the map. Capture crashes stay in
+    # {#failed_test_files} via {#fail_test}.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @param payload [Hash] wrapped capture with string keys.
+    # @return [void]
+    def accept_capture_payload(test_path, payload)
+      unless wrapped_capture?(payload)
+        fail_test(test_path, "invalid coverage output: missing pass/coverage payload")
+        return
+      end
+
+      record_loaded(payload["loaded_files"])
+
+      unless payload["passed"]
+        @failed_clean_tests << relativize(test_path)
+        return
+      end
+
+      coverage = payload["coverage"]
+      record(coverage, test_path) if coverage.is_a?(Hash)
+    end
+
+    # Re-runs each successfully captured test on a cache hit. Digest equality
+    # cannot prove the current unmutated suite still passes.
+    #
+    # @api private
+    # @param after_fork [Proc, nil] boot-mode fork hook.
+    # @return [void]
+    def verify_cached_clean(after_fork: nil)
+      @test_paths.each do |test_path|
+        rel = relativize(test_path)
+        next if @failed_test_files.include?(rel)
+
+        ok = if @boot_path
+               fork_clean_pass?([absolute(test_path)], after_fork)
+             else
+               subprocess_clean_pass?([test_path])
+             end
+        @failed_clean_tests << rel unless ok
+      end
+    end
+
+    # Re-runs tests whose previous capture crashed. A fixed helper is invisible
+    # to the source/test digest when that capture never recorded `loaded_files`.
+    #
+    # @api private
+    # @param after_fork [Proc, nil] boot-mode fork hook.
+    # @return [void]
+    def retry_failed_captures(after_fork)
+      pending = @failed_test_files.dup
+      return if pending.empty?
+
+      @failed_test_files = []
+      abs_sources = abs_source_paths
+      pending.each do |rel|
+        test_path = @test_paths.find { |t| relativize(t) == rel } || rel
+        if @boot_path
+          payload = fork_capture(absolute(test_path), abs_sources, after_fork)
+          case payload
+          when Hash then accept_capture_payload(test_path, payload)
+          when String
+            fail_test(test_path, @verbose ? "fork capture failed: #{payload}" :
+              "fork capture produced no result (re-run with --verbose for the error)")
+          else fail_test(test_path, "fork capture produced no result")
+          end
+        else
+          payload = capture(test_path)
+          accept_capture_payload(test_path, payload) if payload
+        end
+      end
+    end
+
+    # Runs every successfully captured test together. Per-file capture can miss a
+    # failure that only appears when covering files share one process.
+    #
+    # @api private
+    # @param after_fork [Proc, nil] boot-mode fork hook.
+    # @return [void]
+    def verify_combined_clean(after_fork: nil)
+      runnable = @test_paths.reject { |t| @failed_test_files.include?(relativize(t)) }
+      return if runnable.size < 2
+      return unless @failed_clean_tests.empty?
+
+      ok = if @boot_path
+             fork_clean_pass?(runnable.map { |t| absolute(t) }, after_fork)
+           else
+             subprocess_clean_pass?(runnable)
+           end
+      @failed_clean_tests << "combined suite" unless ok
+    end
+
+    # Runs test files in a fresh interpreter and returns whether they passed.
+    #
+    # @api private
+    # @param test_paths [Array<String>] test file paths.
+    # @return [Boolean]
+    def subprocess_clean_pass?(test_paths)
+      status = nil
+      Open3.popen2(RbConfig.ruby, "-") do |stdin, stdout, wait_thr|
+        stdin.write(clean_check_script(test_paths))
+        stdin.close
+        reader = Thread.new { stdout.read }
+        unless wait_thr.join(@capture_timeout)
+          Process.kill(:KILL, wait_thr.pid) rescue nil # rubocop:disable Style/RescueModifier
+          reader.kill
+          return false
+        end
+        reader.join
+        status = wait_thr.value
+      end
+      status&.success?
+    end
+
+    # Runs test files in a fork of the booted parent and returns whether they passed.
+    # Bounded by `@capture_timeout` so a hung child cannot block the CLI.
+    #
+    # @api private
+    # @param abs_tests [Array<String>] absolute test file paths.
+    # @param after_fork [Proc, nil] boot-mode fork hook.
+    # @return [Boolean]
+    def fork_clean_pass?(abs_tests, after_fork)
+      rd, wr = IO.pipe
+      rd.binmode
+      wr.binmode
+      pid = fork do
+        rd.close
+        Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
+        begin
+          after_fork&.call
+          Coverage.result(clear: true, stop: false) if Coverage.running?
+          wr.write(Marshal.dump(TestRunners.for(@framework).run(abs_tests).zero?))
+        rescue Exception # rubocop:disable Lint/RescueException
+          wr.write(Marshal.dump(false))
+        ensure
+          wr.close
+          exit!(0)
+        end
+      end
+      wr.close
+      readable, = IO.select([rd], nil, nil, @capture_timeout)
+      unless readable
+        kill_fork_clean(pid)
+        rd.close
+        return false
+      end
+      data = rd.read
+      rd.close
+      Process.waitpid2(pid)
+      return false if data.empty?
+
+      Marshal.load(data)
+    rescue StandardError
+      false
+    end
+
+    # SIGKILLs a hung clean-check child (and its group) then reaps it.
+    #
+    # @api private
+    # @param pid [Integer] child pid.
+    # @return [void]
+    def kill_fork_clean(pid)
+      begin
+        Process.kill(:KILL, -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        Process.kill(:KILL, pid) rescue nil # rubocop:disable Style/RescueModifier
+      end
+      Process.waitpid2(pid) rescue nil # rubocop:disable Style/RescueModifier
+    end
+
+    # Builds a pass/fail-only subprocess script (no coverage instrumentation).
+    #
+    # @api private
+    # @param test_paths [Array<String>] test file paths.
+    # @return [String] Ruby script text.
+    def clean_check_script(test_paths)
+      @framework == "rspec" ? rspec_clean_check_script(test_paths) : minitest_clean_check_script(test_paths)
+    end
+
+    # Minitest clean-suite check. Preloads configured sources like capture and
+    # standalone {Runner.execute}, so tests that rely on that preload stay green.
+    #
+    # @api private
+    # @param test_paths [Array<String>] test file paths.
+    # @return [String] Ruby script text.
+    def minitest_clean_check_script(test_paths)
+      loads = Array(test_paths).map { |t| "load #{absolute(t).inspect}" }.join("\n")
+      <<~RUBY
+        require "minitest"
+        require "stringio"
+        def Minitest.autorun; end
+        $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
+        #{abs_source_paths.inspect}.each { |f| load f }
+        #{loads}
+        $stdout = StringIO.new
+        exit(Minitest.run([]) ? 0 : 1)
+      RUBY
+    end
+
+    # RSpec clean-suite check. Preloads configured sources like capture.
+    #
+    # @api private
+    # @param test_paths [Array<String>] spec file paths.
+    # @return [String] Ruby script text.
+    def rspec_clean_check_script(test_paths)
+      specs = Array(test_paths).map { |t| absolute(t).inspect }.join(", ")
+      <<~RUBY
+        require "stringio"
+        begin
+          require "rspec/core"
+        rescue LoadError
+          exit 3
+        end
+        RSpec::Core::Runner.disable_autorun!
+        $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
+        #{abs_source_paths.inspect}.each { |f| load f }
+        _sink = StringIO.new
+        $stdout = _sink
+        status = RSpec::Core::Runner.run(["--no-color", #{specs}], _sink, _sink)
+        exit(status.zero? ? 0 : 1)
+      RUBY
+    end
+
     # Builds the framework-specific subprocess script.
     #
     # @api private
@@ -334,9 +594,10 @@ module Mutineer
         load #{absolute(test_path).inspect}
         _orig = $stdout
         $stdout = StringIO.new
-        Minitest.run([])
+        _passed = Minitest.run([])
         $stdout = _orig
-        puts Coverage.result.to_json
+        puts JSON.generate("passed" => _passed == true, "coverage" => Coverage.result,
+                           "loaded_files" => #{loaded_files_expression})
       RUBY
     end
 
@@ -363,9 +624,10 @@ module Mutineer
         _orig = $stdout
         _sink = StringIO.new
         $stdout = _sink
-        RSpec::Core::Runner.run(["--no-color", #{absolute(test_path).inspect}], _sink, _sink)
+        _status = RSpec::Core::Runner.run(["--no-color", #{absolute(test_path).inspect}], _sink, _sink)
         $stdout = _orig
-        puts Coverage.result.to_json
+        puts JSON.generate("passed" => _status.zero?, "coverage" => Coverage.result,
+                           "loaded_files" => #{loaded_files_expression})
       RUBY
     end
 
@@ -387,6 +649,101 @@ module Mutineer
       end
     end
 
+    # Ruby source of the child-side `$LOADED_FEATURES` filter (project `.rb` files).
+    #
+    # @api private
+    # @return [String] expression to embed in a capture subprocess script.
+    def loaded_files_expression
+      root = project_root_real
+      prefix = root.end_with?("/") ? root : "#{root}/"
+      "begin; _root = #{prefix.inspect}; $LOADED_FEATURES.filter_map { |f| next unless f.end_with?(\".rb\"); abs = (File.realpath(f) rescue next); abs if abs.start_with?(_root) }; rescue StandardError; []; end"
+    end
+
+    # Canonical project root for loaded-feature matching (`/var` vs `/private/var`).
+    #
+    # @api private
+    # @return [String] realpath of the project root when it exists.
+    def project_root_real
+      File.realpath(File.expand_path(@project_root))
+    rescue Errno::ENOENT
+      File.expand_path(@project_root)
+    end
+
+    # Project-local `.rb` files loaded in this process at capture time.
+    #
+    # @api private
+    # @return [Array<String>] absolute realpaths.
+    def capture_loaded_files
+      prefix = project_root_real
+      prefix = "#{prefix}/" unless prefix.end_with?("/")
+      $LOADED_FEATURES.filter_map do |f|
+        next unless f.end_with?(".rb")
+
+        abs = File.realpath(f)
+        abs if abs.start_with?(prefix)
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+
+    # Fingerprints project-local support files from a capture payload.
+    #
+    # @api private
+    # @param paths [Array, nil] absolute loaded-file paths.
+    # @return [void]
+    def record_loaded(paths)
+      Array(paths).each do |raw|
+        next unless raw.is_a?(String) && File.file?(raw)
+
+        abs = File.realpath(raw)
+        rel = loaded_relative(abs)
+        next unless rel
+        next unless rel.end_with?(".rb")
+        next if rel.start_with?("vendor/bundle/") || rel.start_with?("node_modules/")
+
+        @loaded_dependencies[rel] = file_fingerprint(abs)
+      end
+    end
+
+    # Path of `abs` relative to the real project root, or nil when outside it.
+    #
+    # @api private
+    # @param abs [String] absolute realpath.
+    # @return [String, nil]
+    def loaded_relative(abs)
+      root = project_root_real
+      prefix = root.end_with?("/") ? root : "#{root}/"
+      return unless abs.start_with?(prefix)
+
+      abs.delete_prefix(prefix)
+    end
+
+    # Byte fingerprint of a file for cache dependency checks.
+    #
+    # @api private
+    # @param abs [String] absolute path.
+    # @return [String] hex digest.
+    def file_fingerprint(abs)
+      content = File.binread(abs)
+      Digest::SHA256.hexdigest("#{content.bytesize}\0#{content}")
+    end
+
+    # True when the cached map recorded support-file fingerprints and they still
+    # match. Missing validity data is a miss (rebuild).
+    #
+    # @api private
+    # @param cached [Hash] parsed coverage.json.
+    # @return [Boolean]
+    def dependencies_match?(cached)
+      deps = cached["dependencies"]
+      return false unless deps.is_a?(Hash)
+
+      deps.all? do |rel, fingerprint|
+        abs = absolute(rel)
+        File.file?(abs) && file_fingerprint(abs) == fingerprint
+      end
+    end
+
     # Digest each file's ROLE + relative path + content length + content, plus
     # the load_paths. Without role/path/length delimiters the digest collides
     # (("ab","c") == ("a","bc")) and is blind to source/test role swaps, silently
@@ -462,8 +819,11 @@ module Mutineer
     # @api private
     # @return [void]
     def save
+      return unless @failed_clean_tests.empty?
+
       FileUtils.mkdir_p(@cache_dir)
-      data = { "digest" => @digest, "failed_test_files" => @failed_test_files, "map" => @map }
+      data = { "digest" => @digest, "failed_test_files" => @failed_test_files,
+               "dependencies" => @loaded_dependencies, "map" => @map }
       tmp = "#{cache_path}.tmp"
       File.write(tmp, JSON.generate(data))
       File.rename(tmp, cache_path) # atomic swap
@@ -494,9 +854,13 @@ module Mutineer
     # @param path [String] path to relativize.
     # @return [String] relative path.
     def relativize(path)
-      return path unless path.start_with?("/")
+      abs = path.start_with?("/") ? path : absolute(path)
+      abs = realpath_if_exists(abs)
+      root = project_root_real
+      prefix = root.end_with?("/") ? root : "#{root}/"
+      return abs unless abs.start_with?(prefix)
 
-      path.delete_prefix("#{@project_root}/")
+      abs.delete_prefix(prefix)
     end
 
     # Expands a path relative to the project root.
@@ -505,7 +869,17 @@ module Mutineer
     # @param path [String] path to expand.
     # @return [String] absolute path.
     def absolute(path)
-      File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
+      raw = File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
+      realpath_if_exists(raw)
+    end
+
+    # Real path when the file exists, otherwise `path` unchanged.
+    #
+    # @api private
+    # @param path [String] absolute or relative path.
+    # @return [String]
+    def realpath_if_exists(path)
+      File.exist?(path) ? File.realpath(path) : path
     end
   end
 end

data/lib/mutineer/daemon_backend.rb

@@ -105,6 +105,17 @@ module Mutineer
       ensure
         client.quit
       end
+      # A red unmutated suite must abort, even when the shipped map is empty.
+      # Falling back to the full --test set would treat those failures as kills.
+      if data.is_a?(Hash) && Array(data["failed_clean_tests"]).any?
+        Runner.abort_if_unclean!(CoverageMap.from_data(
+          map: data["map"] || {},
+          failed_test_files: data["failed_test_files"] || [],
+          project_root: config.project_root,
+          failed_clean_tests: data["failed_clean_tests"]
+        ))
+      end
+
       unless data && !(data["map"] || {}).empty?
         reason = data.is_a?(Hash) && data["error"] ? data["error"] : "empty map"
         warn_coverage_fallback(reason)

data/lib/mutineer/daemon_client.rb

@@ -87,10 +87,13 @@ module Mutineer
     end
 
     # Ask the daemon to build the coverage map app-side and return it. One-shot
-    # control message (no id). Returns `{"map"=>..., "failed_test_files"=>...}`
-    # (possibly with an `"error"`), or nil if the daemon vanished. The caller then
-    # falls back to running the full test set (no narrowing) rather than
-    # mis-scoring.
+    # control message (no id). On success, returns
+    # `{"map"=>..., "failed_test_files"=>..., "failed_clean_tests"=>...}`.
+    # On coverage-build failure, returns
+    # `{"map"=>{}, "failed_test_files"=>[], "error"=>...}`.
+    # Returns nil if the daemon vanished. The caller then falls back to running
+    # the full test set (no narrowing) rather than mis-scoring, except a red
+    # unmutated suite which aborts.
     #
     # @return [Hash, nil] the coverage payload, or nil on a dead pipe.
     def coverage

data/lib/mutineer/daemon_server.rb

@@ -150,7 +150,8 @@ module Mutineer
           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 }
+        { "map" => cmap.map, "failed_test_files" => cmap.failed_test_files,
+          "failed_clean_tests" => cmap.failed_clean_tests }
       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}" }

data/lib/mutineer/file_swap.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
+require "digest"
+require "fileutils"
+
 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.
+  # Raised when another process already holds exclusive ownership of a source
+  # file. Aborting beats silently restoring (or capturing) the other run's mutant.
   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.")
+    def initialize(path)
+      super("another mutineer run owns #{path} — aborting to avoid corrupting the source file.")
     end
   end
 
@@ -19,51 +20,92 @@ module Mutineer
   #
   # Defense in depth, mirroring the tempfile-orphan discipline
   # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
+  #   - exclusive OS ownership (flock) is acquired before swap or recovery;
   #   - 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.
+  #     can self-heal a left-mutated tree on the next run's startup once the
+  #     kernel has released the dead owner's lock.
   # 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"
 
+    # Subdirectory beside the source that holds flock files (stable across cwd
+    # and `cache_dir`, so concurrent runs on one inode share one lock).
+    LOCK_DIR_NAME = "file-swap-locks"
+
+    # Canonical source path => open lock File held by this process.
+    # @api private
+    OWNED = {}
+
+    # Real path when the file exists, otherwise `File.expand_path`. Symlink
+    # aliases of one inode share this identity for locks, backups, and ownership.
+    #
+    # @param path [String] source path, relative or absolute.
+    # @return [String] canonical absolute path.
+    def self.canonical_path(path)
+      expanded = File.expand_path(path)
+      File.exist?(expanded) ? File.realpath(expanded) : expanded
+    end
+
+    # Holds exclusive OS ownership of each source path for the duration of the
+    # block. Re-entrant for paths this process already owns. Raises
+    # {ConcurrentRunError} when another process holds a path (non-blocking).
+    #
+    # @param paths [Array<String>] source file paths to own.
+    # @yield the block to run while ownership is held.
+    # @return [Object] the block's return value.
+    def self.owning(paths)
+      acquired = []
+      Array(paths).map { |p| canonical_path(p) }.uniq.sort.each do |path|
+        next if OWNED.key?(path)
+
+        acquire!(path)
+        acquired << path
+      end
+      yield
+    ensure
+      acquired.reverse_each { |path| release!(path) }
+    end
+
     # 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.
+    # Acquires exclusive ownership first; a leftover backup with no live owner is
+    # treated as the original (a prior hard-killed run), not a concurrent run.
     #
     # @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)
+      path = canonical_path(source_file)
+      created = false
+      original = nil
+      backup = path + BACKUP_SUFFIX
+      owning([path]) do
+        begin
+          original = File.exist?(backup) ? File.binread(backup) : File.binread(path)
+          File.binwrite(backup, original)
+          created = true
+          File.binwrite(path, mutated)
+          yield
+        ensure
+          if created
+            File.binwrite(path, original)
+            File.unlink(backup) if File.exist?(backup)
+          end
+        end
       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).
+    # Skips a backup whose source is owned by a live process. 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]
@@ -72,19 +114,10 @@ module Mutineer
       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).
+          begin
+            owning([source_file]) { healed += restore_one(backup, source_file) }
+          rescue ConcurrentRunError
             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 does not see a false race.
-            File.unlink(backup)
-          else
-            File.binwrite(source_file, backup_bytes)
-            File.unlink(backup)
-            healed += 1
           end
         end
       end
@@ -92,5 +125,68 @@ module Mutineer
 
       warn "[mutineer] restored #{healed} source file(s) left mutated by a previous interrupted run."
     end
+
+    # Exclusive non-blocking flock for canonical `path`.
+    #
+    # @api private
+    # @param path [String] canonical source path.
+    # @return [void]
+    # @raise [Mutineer::ConcurrentRunError] when the lock is held elsewhere.
+    def self.acquire!(path)
+      file = File.open(lock_file(path), File::RDWR | File::CREAT, 0o644)
+      unless file.flock(File::LOCK_EX | File::LOCK_NB)
+        file.close
+        raise ConcurrentRunError, path
+      end
+      OWNED[path] = file
+    end
+
+    # Flock path for a canonical source: `<dir>/.mutineer/file-swap-locks/<sha>`.
+    # Derived only from the source path so cwd and `cache_dir` cannot split a lock.
+    #
+    # @api private
+    # @param path [String] canonical source path.
+    # @return [String] lock file path.
+    def self.lock_file(path)
+      dir = File.join(File.dirname(path), ".mutineer", LOCK_DIR_NAME)
+      FileUtils.mkdir_p(dir)
+      File.join(dir, Digest::SHA256.hexdigest(path))
+    end
+
+    # Releases a lock acquired by {acquire!}.
+    #
+    # @api private
+    # @param path [String] expanded source path.
+    # @return [void]
+    def self.release!(path)
+      file = OWNED.delete(path)
+      return unless file
+
+      file.flock(File::LOCK_UN)
+      file.close
+    rescue StandardError
+      nil
+    end
+
+    # Restores one backup if the sibling source exists. Returns 1 when bytes
+    # were written back, 0 when the backup was redundant or had no sibling.
+    #
+    # @api private
+    # @param backup [String] path to the `*.mutineer-backup` file.
+    # @param source_file [String] corresponding source path.
+    # @return [Integer] 1 if healed, otherwise 0.
+    def self.restore_one(backup, source_file)
+      return 0 unless File.exist?(source_file)
+
+      backup_bytes = File.binread(backup)
+      if File.binread(source_file) == backup_bytes
+        File.unlink(backup)
+        0
+      else
+        File.binwrite(source_file, backup_bytes)
+        File.unlink(backup)
+        1
+      end
+    end
   end
 end

data/lib/mutineer/runner.rb

@@ -99,6 +99,7 @@ module Mutineer
           load_paths: config.load_paths, framework: config.framework
         ).build_or_load
       end
+      abort_if_unclean!(coverage_map)
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
       jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
@@ -184,44 +185,50 @@ module Mutineer
     # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
     def self.execute_external(config, operator_classes)
       abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
-      dirs      = source_dirs(config)
+      sources   = config.sources.map { |s| FileSwap.canonical_path(File.expand_path(s, config.project_root)) }
+      dirs      = sources.map { |s| File.dirname(s) }.uniq
+
+      # Own every source before healing leftovers or reading bytes for mutation.
+      # A backup file alone is not ownership; flock is. Canonical paths so
+      # symlink aliases of one inode share one lock, independent of cache_dir.
+      FileSwap.owning(sources) do
+        # Heal any file a prior hard-killed run left mutated BEFORE reading source.
+        # collect_jobs computes mutation offsets/ids from the on-disk bytes, so a
+        # still-mutated file would yield garbage offsets against the later-healed
+        # source. Heal first, then discover jobs from the clean tree.
+        FileSwap.restore_orphans(dirs)
 
-      # Heal any file a prior hard-killed run left mutated BEFORE reading source.
-      # collect_jobs computes mutation offsets/ids from the on-disk bytes, so a
-      # still-mutated file would yield garbage offsets against the later-healed
-      # source. Heal first, then discover jobs from the clean tree.
-      FileSwap.restore_orphans(dirs)
+        jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+        jobs = filter_since(jobs, source_map, config) if config.since
 
-      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
-      jobs = filter_since(jobs, source_map, config) if config.since
+        # Nothing to mutate: return before the smoke check, which runs the whole
+        # --test set to calibrate a timeout no mutant would use (#76).
+        next [AggregateResult.new(ignored_results), source_map] if jobs.empty?
+
+        # Calibrate the per-mutant timeout from the clean run (a real suite far
+        # outlasts the 10s in-process fork budget), and abort if it is not green.
+        # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
+        # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
+        # handful cannot stall a serial run for ~45min on a slow suite.
+        smoke_elapsed = ExternalBackend.smoke_check!(config.test_command, abs_tests)
+        timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
 
-      # Nothing to mutate: return before the smoke check, which runs the whole
-      # --test set to calibrate a timeout no mutant would use (#76).
-      return [AggregateResult.new(ignored_results), source_map] if jobs.empty?
-
-      # Calibrate the per-mutant timeout from the clean run (a real suite far
-      # outlasts the 10s in-process fork budget), and abort if it is not green.
-      # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
-      # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
-      # handful cannot stall a serial run for ~45min on a slow suite.
-      smoke_elapsed = ExternalBackend.smoke_check!(config.test_command, abs_tests)
-      timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
-
-      results = []
-      progress = Progress.new(jobs.size)
-      begin
-        jobs.each do |subject, mutation, id|
-          r = run_external(subject, mutation, config.test_command, abs_tests,
-                           timeout: timeout, verbose: config.verbose)
-          results << r.with(subject: subject, mutation: mutation, id: id)
-          progress.tick
-          break if config.fail_fast && r.survived? # stop at the first survivor
+        results = []
+        progress = Progress.new(jobs.size)
+        begin
+          jobs.each do |subject, mutation, id|
+            r = run_external(subject, mutation, config.test_command, abs_tests,
+                             timeout: timeout, verbose: config.verbose)
+            results << r.with(subject: subject, mutation: mutation, id: id)
+            progress.tick
+            break if config.fail_fast && r.survived? # stop at the first survivor
+          end
+        ensure
+          FileSwap.restore_orphans(dirs)
         end
-      ensure
-        FileSwap.restore_orphans(dirs)
-      end
 
-      [AggregateResult.new(results + ignored_results), source_map]
+        [AggregateResult.new(results + ignored_results), source_map]
+      end
     end
 
     # Runs one mutant through the external backend: apply the whole-file mutation
@@ -241,6 +248,21 @@ module Mutineer
       end
     end
 
+    # Aborts the run when coverage capture saw a red unmutated suite. Scoring
+    # those results would treat existing assertion failures as killed mutants.
+    #
+    # @param coverage_map [Mutineer::CoverageMap] the built or loaded map.
+    # @return [void]
+    # @raise [Mutineer::SmokeCheckError] when any captured test failed clean.
+    def self.abort_if_unclean!(coverage_map)
+      files = coverage_map.failed_clean_tests
+      return if files.empty?
+
+      raise SmokeCheckError,
+            "the unmutated suite is not green (#{files.join(', ')}) — " \
+            "#{ExternalBackend.generic_env_hint}."
+    end
+
     # Coverage-based test selection, shared by the in-process ({run}) and daemon
     # paths so both narrow identically (score parity). Returns
     # `[:run, abs_test_paths]` when some test covers the mutant's line, or

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - David Teren
@@ -114,6 +114,7 @@ metadata:
   source_code_uri: https://github.com/davidteren/mutineer
   changelog_uri: https://github.com/davidteren/mutineer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/davidteren/mutineer/issues
+  documentation_uri: https://davidteren.github.io/mutineer/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: