mutineer 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d61c927b33961995a0d38b691cdf0b34a6e9041213980c0cd7a3a01f457f875
-  data.tar.gz: 8e4f32e923344837ab664805a3099a9e67d405bbe7b63d83986d1af0b488ead5
+  metadata.gz: 92b74299812649a42303c4387412bd3bd67014e7e91c656df36489836773ae08
+  data.tar.gz: 20c25fed6e5a490deb8d5f9068cd47187efe16fdfa0625a18e9e1fe7296b17f6
 SHA512:
-  metadata.gz: 5ea750d511b52ef0f9d320c39ef0b4a3b51189116c09811b3bf4f2d5752b026d1ddc62411387a261f6f60ba73e23e2b76af1e553a745bd63f9a3d56a0cd068cb
-  data.tar.gz: 6dc10950ea34998e459e5007095bd43df87a633a4ca18e19afee1812a8fed154e086f3ae3a7b808bd84ba93336bb61208195d001efd846fea367502a23167ef2
+  metadata.gz: 0d838506311eff5c879ee9b23701a995c112a84ce4d7e0cfa9d1b43788ff39eb39cfafcbc4111db1547feb5f5874c0f5e07489f2c7597235c3cd37ef360d407f
+  data.tar.gz: 15ec124714bb63d42a2ac95e5ea8582f4329f7577e8fabfe7e544fe062e5667b60bcb9b3d07b167e731c3b7980a7c71ed18f368b7c8fe4d32d20f28021e0cdb0

data/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.10.0] - 2026-07-02
+
+### Added
+- **`--test-command` external backend** (#27) — mutation-test apps pinned to Ruby
+  < 3.4. Mutineer stays on ≥ 3.4 but runs your suite as a subprocess in the app's
+  own runtime via `--test-command "bundle exec rails test %{files}"` (`%{files}`
+  expands to the `--test` paths; env is inherited). The mutant is applied on disk
+  with crash-safe backup/restore (self-heals a hard-killed run on next startup); a
+  smoke check aborts before scoring if the unmutated suite isn't green. This path
+  is reload-only, serial (`--jobs` forced to 1), and does no coverage narrowing —
+  so its score is an upper bound, not comparable to an in-process `--rails` score
+  (Mutineer prints this caveat). Also settable as `test_command:` in `.mutineer.yml`.
+  Safe parallelism for this path is tracked in #26.
+
 ## [0.9.1] - 2026-07-01
 
 ### Fixed

data/README.md

@@ -56,6 +56,7 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
+| `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](#apps-on-ruby--34) |
 | `--format human\|json\|html` | Report format (default: human; `html` is a self-contained file) |
 | `--output FILE` | Write the report to FILE instead of stdout |
 | `--dry-run` | List candidate mutations without executing (honors suppression) |
@@ -103,6 +104,40 @@ Add Mutineer to your Gemfile's test group:
 gem "mutineer", group: :test, require: false
 ```
 
+### Apps on Ruby < 3.4
+
+Mutineer's own process needs Ruby ≥ 3.4 (it parses with stdlib Prism), and the
+`--rails` path above boots your app *inside Mutineer's process* — so it can't run
+against an app pinned to an older Ruby (`ruby "3.1.6"` in the Gemfile), where the
+bundle rejects 3.4.
+
+`--test-command` decouples the two: Mutineer stays on ≥ 3.4, but your suite runs
+as a **subprocess in your app's own runtime** (whatever Ruby its bundle resolves
+to). Run Mutineer with a 3.4+ Ruby and hand it the command that runs your tests:
+
+```sh
+RAILS_ENV=test mutineer run app/models/order.rb \
+  --test test/models/order_test.rb \
+  --test-command "bundle exec rails test %{files}"
+```
+
+- **`%{files}`** is required; it expands to the `--test` paths as separate
+  arguments (a path with a space stays one argument — there is no shell).
+- **Environment** is inherited by the subprocess, so set it on the Mutineer
+  command (e.g. the leading `RAILS_ENV=test` above). Don't put `KEY=val` inside
+  `--test-command`.
+
+Tradeoffs (Phase 1) — this path is correct but not free:
+
+- **Slower:** your app re-boots for every mutant (no shared boot yet).
+- **No coverage narrowing:** every mutant runs the *full* `--test` set, so the
+  score is an **upper bound and not comparable to an in-process (`--rails`)
+  score** — uncovered mutants count as survivors, and an infrastructure failure
+  is scored as a kill. Mutineer prints this caveat on every run and aborts up
+  front (a "smoke check") if your unmutated suite isn't green.
+- **Reload strategy only** (`--strategy redefine` is rejected on this path) and
+  **serial** (`--jobs` is forced to 1 — safe parallelism is tracked in #26).
+
 ## Suppressing equivalent mutants
 
 Some mutants are equivalent (behaviour-identical) and survive forever — keeping a
@@ -166,7 +201,9 @@ walking up). CLI flags override config; config overrides defaults.
 
 Sources are positional CLI arguments and test files come from `--test`; the
 config file accepts these keys: `operators`, `threshold`, `jobs`, `only`,
-`require` (extra files to load before mutating), and `boot`/`rails`.
+`require` (extra files to load before mutating), `boot`/`rails`, and
+`test_command` (the external-runtime suite command — see
+[Apps on Ruby < 3.4](#apps-on-ruby--34)).
 
 ```yaml
 # .mutineer.yml

data/lib/mutineer/cli.rb

@@ -47,6 +47,10 @@ module Mutineer
         --boot FILE          Require FILE once in the parent to boot the app env, then
                              fork per mutant (Rails apps; requires --test)
         --rails              Sugar for --boot config/environment --strategy redefine
+        --test-command CMD   Run the target suite in the app's own runtime as a
+                             subprocess (for apps on Ruby < 3.4). CMD must contain
+                             %{files} (expands to the --test paths). Env is inherited,
+                             e.g. RAILS_ENV=test mutineer run ... --test-command "..."
         --format human|json|html  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
@@ -105,6 +109,9 @@ module Mutineer
         # typed (CLI wins over the file). --baseline-epsilon is CLI-only.
         o.on("--baseline FILE") { |v| opts[:baseline] = v; explicit << :baseline }
         o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = v.to_f }
+        # #27: run the target suite as a subprocess in the app's OWN runtime so
+        # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
+        o.on("--test-command CMD") { |v| opts[:test_command] = v; explicit << :test_command }
       end
 
       begin
@@ -188,6 +195,11 @@ module Mutineer
     rescue Mutineer::ParseError => e
       warn "mutineer: error reading: #{e.message}"
       exit 1
+    rescue Mutineer::SmokeCheckError => e
+      # #27: the unmutated suite isn't green under --test-command — a broken
+      # environment, not weak tests. Runtime error (exit 1), not usage (exit 2).
+      warn "mutineer: #{e.message}"
+      exit 1
     end
 
     # Flag validation: every flag/usage failure exits 2 (C7), consistent with the
@@ -229,6 +241,8 @@ module Mutineer
         exit 2
       end
 
+      validate_test_command!(config) if config.test_command
+
       validate_since!(config) if config.since
       preflight_output!(config.output) if config.output
       preflight_baseline!(config.baseline) if config.baseline
@@ -250,6 +264,42 @@ module Mutineer
       validate_paths!(config)
     end
 
+    # #27: --test-command runs the target suite in the app's own runtime. Validate
+    # its shape up front (usage errors → exit 2) and force serial execution: each
+    # subprocess boots the app and opens its own fixture transaction against the
+    # same DB, so --jobs > 1 would corrupt results (the #12 fixture-contention
+    # hazard). Unlike --rails, this path has NO per-worker DB isolation to opt into,
+    # so an explicit --jobs N is forced to 1 rather than honored (KTD-5).
+    # Validates the --test-command configuration.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
+    def self.validate_test_command!(config)
+      if config.test_command.strip.empty?
+        warn "mutineer: --test-command must not be empty"
+        exit 2
+      end
+      unless config.test_command.include?("%{files}")
+        warn "mutineer: --test-command must contain %{files} (where the --test paths are substituted)"
+        exit 2
+      end
+      if config.boot
+        warn "mutineer: --test-command cannot be combined with --boot/--rails " \
+             "(the external subprocess boots the app itself)"
+        exit 2
+      end
+      if config.strategy == "redefine"
+        warn "mutineer: --test-command supports only --strategy reload " \
+             "(surgical redefine needs a shared VM; the subprocess has its own)"
+        exit 2
+      end
+      return unless config.jobs > 1
+
+      warn "[mutineer] --test-command runs serially (no per-worker DB isolation yet); forcing --jobs 1."
+      config.jobs = 1
+    end
+
     # --since needs a real git repo and a resolvable ref; either failure is a
     # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
     # Validates the --since ref.
@@ -377,6 +427,16 @@ module Mutineer
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
                       format: config.format, output: config.output, baseline: delta)
 
+      # #27/KTD-6: warn (stderr, so it never pollutes json/html) that an external
+      # run's score is not comparable to an in-process run — it has no coverage
+      # narrowing, so uncovered mutants count as survivors, and an infra failure is
+      # scored as a kill (upper bound).
+      if config.test_command
+        warn "[mutineer] --test-command score is an upper bound, not comparable to an " \
+             "in-process run: no coverage narrowing (uncovered mutants count as survivors) " \
+             "and an infra failure is scored as a kill."
+      end
+
       # #14: nudge toward the opt-in tier-2 operators (human report only — never
       # pollute JSON output).
       if !%w[json html].include?(config.format) && (hint = tier2_hint(config.operators))

data/lib/mutineer/config.rb

@@ -25,13 +25,17 @@ module Mutineer
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
     :boot, :rails, :since, :framework, :verbose, :ignore,
-    :baseline, :baseline_epsilon, :fail_fast,
+    # :daemon / :daemon_timeout are NOT user-facing yet — no CLI flag or KNOWN_KEYS
+    # entry until the Phase 2c `--daemon` unit lands (which adds the flag + a `to_i`
+    # coerce + KNOWN_KEYS). For now they're set programmatically (tests/Runner).
+    :baseline, :baseline_epsilon, :fail_fast, :test_command,
+    :daemon, :daemon_timeout,
     keyword_init: true
   ) do
     # Config file name.
     CONFIG_FILE = ".mutineer.yml"
     # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
-    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast].freeze
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast test_command].freeze
 
     def initialize(**kwargs)
       super
@@ -51,6 +55,7 @@ module Mutineer
       self.ignore        ||= []
       self.baseline_epsilon ||= 0.0
       self.fail_fast     = false if fail_fast.nil?
+      self.daemon        = false if daemon.nil?
     end
 
     # Walk from `start` toward `home`, returning the first .mutineer.yml path found
@@ -166,6 +171,7 @@ module Mutineer
       when "verbose"   then value == true || value.to_s == "true"
       when "ignore"    then Array(value).map(&:to_s)
       when "baseline"  then value.to_s
+      when "test_command" then value.to_s
       else value
       end
     end

data/lib/mutineer/daemon_client.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Mutineer
+  # Raised when the daemon cannot be booted (bad boot path, app error, or it dies on
+  # the handshake). The CLI maps it to a runtime error.
+  class DaemonBootError < StandardError; end
+
+  # #26/#27 Phase 2a — the TOOL-side handle for the app-side daemon.
+  #
+  # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY (cleaned env so the gem's
+  # bundler context never leaks; the daemon file is loaded by absolute path with
+  # `-r`, which bypasses the app bundle that has no mutineer), completes the ready
+  # handshake, then ships per-mutant payloads and reads structured verdicts. If the
+  # daemon dies mid-run it respawns (bounded) and marks the in-flight mutant `error`
+  # rather than corrupting the run. Reuses the cleaned-env spawn + stderr-drain proven
+  # in the spike driver and the spawn discipline of ExternalBackend.
+  class DaemonClient
+    # Absolute path to the daemon entry, loaded app-side by `-r` (bypasses the bundle).
+    DAEMON_PATH = File.expand_path("daemon_server.rb", __dir__)
+    # How many times to respawn a crashing daemon before aborting the run.
+    MAX_RESTARTS = 3
+
+    # @param boot [Hash] boot config sent to the daemon: project_root, boot,
+    #   load_paths, framework, rails.
+    # @param app_root [String] directory to spawn the daemon in (the app root).
+    # @param ruby_version [String, nil] RBENV_VERSION for the app's Ruby (nil = inherit).
+    # @param gemfile [String, nil] BUNDLE_GEMFILE for the app's bundle (nil = app_root/Gemfile).
+    # @param errio [IO] where daemon stderr is drained.
+    def initialize(boot:, app_root:, ruby_version: nil, gemfile: nil, errio: $stderr)
+      @boot = boot
+      @app_root = app_root
+      @ruby_version = ruby_version
+      @gemfile = gemfile || File.join(app_root, "Gemfile")
+      @errio = errio
+      @restarts = 0
+    end
+
+    # Spawn the daemon and complete the ready handshake. Raises DaemonBootError on
+    # failure (surfaced by the CLI as a clean runtime error, not a hang).
+    #
+    # @return [self]
+    def start
+      spawn_daemon
+      self
+    end
+
+    # Run one mutant: ship the payload + covering tests, return the verdict string.
+    # On a daemon crash (EOF/dead pipe) respawn (bounded) and return `"error"` for
+    # this mutant — never a wrong verdict, never a wedged run.
+    #
+    # @param id [Integer] request id (echoed back for ordering safety).
+    # @param payload [Hash] {"code" => mutated ruby, "source_file" => path}.
+    # @param tests [Array<String>] covering test file paths.
+    # @param timeout [Numeric] per-mutant wall-clock timeout (seconds).
+    # @return [String] one of survived/killed/error/timeout.
+    def request(id:, payload:, tests:, timeout:)
+      # A crash can surface on the WRITE (daemon died idle between requests →
+      # Errno::EPIPE) as well as the read (EOF), so guard both: either way, respawn
+      # for future mutants and score THIS one error (re-running a crash-causing
+      # mutant could loop). Never let a dead pipe abort the whole run.
+      reply =
+        begin
+          send_line("id" => id, "payload" => payload, "tests" => tests, "timeout" => timeout)
+          read_line
+        rescue Errno::EPIPE, IOError
+          nil
+        end
+      return reply["verdict"] if reply && reply["id"] == id
+
+      restart!
+      "error"
+    end
+
+    # Graceful shutdown; leaves no orphaned daemon/child.
+    #
+    # @return [void]
+    def quit
+      return unless @stdin
+
+      send_line("cmd" => "quit") rescue nil # rubocop:disable Style/RescueModifier
+      @wait_thr&.join
+    ensure
+      close_io
+    end
+
+    private
+
+    # Cleaned environment for the app bundle: strip the gem's bundler/Ruby context so
+    # `bundle exec` resolves the APP's Gemfile under the requested Ruby.
+    def app_env
+      env = ENV.to_h.reject { |k, _| k.start_with?("BUNDLE_", "RUBY", "GEM_") }
+      env["BUNDLE_GEMFILE"] = @gemfile
+      env["RBENV_VERSION"] = @ruby_version if @ruby_version
+      env["RAILS_ENV"] ||= "test" if @boot[:rails] || @boot["rails"]
+      env
+    end
+
+    # Spawn the daemon under the app bundle and complete the ready handshake.
+    #
+    # @return [void]
+    # @raise [Mutineer::DaemonBootError] when the daemon fails to boot.
+    def spawn_daemon
+      # Plain `bundle exec ruby` — NOT `rbenv exec`, which would break CI and any
+      # non-rbenv setup. When bundler/ruby are rbenv shims, the RBENV_VERSION carried
+      # in app_env still selects the app's Ruby; otherwise the active Ruby is used.
+      @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(
+        app_env, "bundle", "exec", "ruby",
+        "-r", DAEMON_PATH, "-e", "Mutineer::DaemonServer.run", chdir: @app_root
+      )
+      # Drain daemon stderr to the tool's stderr so child/boot errors are visible.
+      # Tracked (not fire-and-forget) so close_io can reclaim it on quit/respawn; the
+      # rescue swallows the benign EBADF/IOError raised when close_io closes the pipe
+      # out from under an in-flight copy_stream.
+      @drain = Thread.new do # rubocop:disable ThreadSafety/NewThread
+        IO.copy_stream(@stderr, @errio)
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      send_line(@boot)
+      ready = read_line
+      unless ready && ready["ready"]
+        detail = ready && ready["error"] ? ready["error"] : "daemon exited before the handshake"
+        close_io
+        raise DaemonBootError, "daemon failed to boot under the app bundle: #{detail}"
+      end
+    end
+
+    # Respawn after a crash, up to MAX_RESTARTS, then hard-fail loudly.
+    def restart!
+      close_io
+      @restarts += 1
+      if @restarts > MAX_RESTARTS
+        raise DaemonBootError, "daemon crashed #{@restarts} times; aborting the run"
+      end
+
+      @errio.puts("[mutineer] daemon crashed — respawning (#{@restarts}/#{MAX_RESTARTS})")
+      spawn_daemon
+    end
+
+    # Write one JSON object as a line to the daemon.
+    #
+    # @param obj [Hash] the message to encode.
+    # @return [void]
+    def send_line(obj)
+      @stdin.puts(JSON.generate(obj))
+      @stdin.flush
+    end
+
+    # Read one JSON reply line; nil on EOF/dead pipe (caller treats as a crash).
+    def read_line
+      line = @stdout.gets
+      line && JSON.parse(line.strip)
+    rescue IOError, Errno::EPIPE, JSON::ParserError
+      nil
+    end
+
+    # Close the IPC pipes, stop the stderr-drain thread, and reap the daemon so a
+    # respawn or quit leaves no leaked fd, thread, or zombie.
+    #
+    # @return [void]
+    def close_io
+      @drain&.kill # stop the drain BEFORE closing its fd (avoids a copy_stream EBADF)
+      [@stdin, @stdout, @stderr].each { |io| io&.close rescue nil } # rubocop:disable Style/RescueModifier
+      @wait_thr&.join # reap the exited daemon so respawn/quit leaves no zombie
+      @stdin = @stdout = @stderr = @drain = @wait_thr = nil
+    end
+  end
+end

data/lib/mutineer/daemon_server.rb

@@ -0,0 +1,190 @@
+# 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}
+  #   ready out: {"ready":true,"ruby":"3.3.6"}   (or {"ready":false,"error":"..."} then exit)
+  #   run  in  : {"id":N,"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"}
+  #
+  # 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 or
+  # boot failure); parent-detected timeout. Tagging an in-TEST DB error as `error`
+  # (vs killed) is a Phase-2b concern (needs the after_fork adapter's re-raise).
+  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"
+
+          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)
+        @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)) }
+        # 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"]
+      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
+
+      # Fork a child to run one mutant in isolation; decode its exit into a verdict.
+      def run_mutant(req)
+        timeout = req.fetch("timeout", 30)
+        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
+              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

data/lib/mutineer/runner.rb

@@ -11,6 +11,9 @@ require_relative "changed_lines"
 require_relative "mutator_registry"
 require_relative "worker_pool"
 require_relative "mutant_id"
+require_relative "file_swap"
+require_relative "external_backend"
+require_relative "daemon_client"
 require "set"
 
 module Mutineer
@@ -38,6 +41,16 @@ module Mutineer
     def self.execute(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
 
+      # #27: the external backend runs the suite as a subprocess in the app's own
+      # runtime — it does no in-process boot/require or coverage build, so branch
+      # before any of that. The in-process path below is untouched.
+      return execute_external(config, operator_classes) if config.test_command
+
+      # #26/#27 Phase 2a: the daemon backend boots the app ONCE in a persistent
+      # subprocess under the app's bundle and forks per mutant. Tool-side we only
+      # discover jobs + build payloads (Prism), so branch before any in-process boot.
+      return execute_daemon(config, operator_classes) if config.daemon
+
       # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
       # in the parent and inherited by every fork. Do NOT manually require the
       # sources — under Zeitwerk a manual require of an autoloadable file raises;
@@ -87,31 +100,7 @@ module Mutineer
       end
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
-      # #10: a mutant the user marked known-equivalent (inline disable-line comment
-      # or .mutineer.yml ignore id) is classified :ignored here and NEVER forked —
-      # it is removed from the killed+survived denominator so a strong file reaches
-      # 100%. The stable id is computed per subject (occurrence needs the full list)
-      # and carried on every job so the parent can reattach it after the run.
-      source_map = {}
-      disabled_map = {}
-      ignore_set = config.ignore.to_set
-      jobs = []
-      ignored_results = []
-      Project.discover(config.sources, only: config.only).each do |subject|
-        source = (source_map[subject.file] ||= File.read(subject.file))
-        disabled = (disabled_map[subject.file] ||= suppress_map(source))
-        mutations = operator_classes.flat_map { |klass| klass.new.mutations_for(subject, source) }
-        ids = MutantId.for_subject(subject, source, mutations)
-        mutations.each_with_index do |mutation, i|
-          id = ids[i]
-          line = source.byteslice(0, mutation.start_offset).count("\n") + 1
-          if suppressed?(mutation.operator, line, id, disabled, ignore_set)
-            ignored_results << Result.ignored.with(subject: subject, mutation: mutation, id: id)
-          else
-            jobs << [subject, mutation, id]
-          end
-        end
-      end
+      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
 
       jobs = filter_since(jobs, source_map, config) if config.since
 
@@ -119,9 +108,8 @@ module Mutineer
       # resolves). A SIGKILL'd child skips the tempfile's ensure-unlink, orphaning
       # it. `ensure` is unreliable vs SIGKILL, so the PARENT sweeps each source dir
       # before and after the run — orphans are impossible after a normal run.
-      source_dirs = config.sources
-                          .map { |f| File.dirname(File.expand_path(f, config.project_root)) }.uniq
-      sweep_orphans(source_dirs)
+      dirs = source_dirs(config)
+      sweep_orphans(dirs)
 
       strategy = config.strategy
       results =
@@ -139,12 +127,183 @@ module Mutineer
           # filter_map drops nils for jobs --fail-fast left unscheduled.
           bare.each_with_index.filter_map { |r, i| r&.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2]) }
         ensure
-          sweep_orphans(source_dirs)
+          sweep_orphans(dirs)
         end
 
       [AggregateResult.new(results + ignored_results), source_map]
     end
 
+    # Collect every (subject, mutation, id) up front so a backend can run them.
+    # #10: a mutant the user marked known-equivalent (inline disable-line comment
+    # or .mutineer.yml ignore id) is classified :ignored here and NEVER run — it is
+    # removed from the killed+survived denominator so a strong file reaches 100%.
+    # The stable id is computed per subject (occurrence needs the full list) and
+    # carried on every job so the parent can reattach it after the run. Shared by
+    # the in-process and external (#27) backends so job selection can never drift.
+    #
+    # @return [Array(Array, Array<Result>, Hash<String,String>)] jobs, ignored, source_map.
+    def self.collect_jobs(config, operator_classes)
+      source_map = {}
+      disabled_map = {}
+      ignore_set = config.ignore.to_set
+      jobs = []
+      ignored_results = []
+      Project.discover(config.sources, only: config.only).each do |subject|
+        source = (source_map[subject.file] ||= File.read(subject.file))
+        disabled = (disabled_map[subject.file] ||= suppress_map(source))
+        mutations = operator_classes.flat_map { |klass| klass.new.mutations_for(subject, source) }
+        ids = MutantId.for_subject(subject, source, mutations)
+        mutations.each_with_index do |mutation, i|
+          id = ids[i]
+          line = source.byteslice(0, mutation.start_offset).count("\n") + 1
+          if suppressed?(mutation.operator, line, id, disabled, ignore_set)
+            ignored_results << Result.ignored.with(subject: subject, mutation: mutation, id: id)
+          else
+            jobs << [subject, mutation, id]
+          end
+        end
+      end
+      [jobs, ignored_results, source_map]
+    end
+
+    # #27: external backend orchestration. Runs each mutant's whole-file mutation on
+    # disk (crash-safe swap) and executes the user's --test-command as a subprocess
+    # in the app's own runtime. Serial by construction (KTD-5: one shared DB, no
+    # per-worker isolation yet). No coverage narrowing — every mutant runs the full
+    # --test set (KTD-6); the score is therefore an upper bound and not comparable
+    # to an in-process run (the CLI discloses this).
+    #
+    # @param config [Mutineer::Config] run configuration (test_command set).
+    # @param operator_classes [Array<Class>] resolved operators.
+    # @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)
+
+      # 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
+
+      # Calibrate the per-mutant timeout from the clean run (a real suite far
+      # outlasts the 10s in-process fork budget), and abort if it isn't green.
+      # ponytail: 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 can't 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 = []
+      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)
+          break if config.fail_fast && r.survived? # #21: stop at the first survivor
+        end
+      ensure
+        FileSwap.restore_orphans(dirs)
+      end
+
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # Runs one mutant through the external backend: apply the whole-file mutation on
+    # disk, run the command, restore. KTD-8: an invalid (non-reparsing) mutant would
+    # fail to load and score a false `killed`, so skip it tool-side (Prism, already
+    # cheap) and never write the file — preserving the `skipped` verdict the
+    # in-process path gives at runner.rb's pre-fork check.
+    #
+    # @return [Mutineer::Result] verdict for this mutant.
+    def self.run_external(subject, mutation, command, abs_tests, timeout:, verbose:)
+      source  = File.read(subject.file)
+      mutated = mutation.apply(source)
+      return Result.skipped if Parser.parse_string(mutated).errors.any?
+
+      FileSwap.with(subject.file, mutated) do
+        ExternalBackend.run(command, abs_tests, timeout: timeout, verbose: verbose)
+      end
+    end
+
+    # #26/#27 Phase 2a — daemon backend orchestration (serial). Boots the app ONCE in
+    # a persistent subprocess and forks per mutant, restoring the one-boot speed the
+    # Phase 1 subprocess path gives up. Tool-side we build the ready-to-`load` payload
+    # (KTD-2/KTD-3: whole-file reload by default — the spike-proven path) and ship it;
+    # the daemon needs no Prism/mutineer. Serial in 2a (worker-DB isolation +
+    # parallelism is Phase 2b). No coverage narrowing yet (Phase 2c), so every mutant
+    # runs the full `--test` set.
+    #
+    # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
+    def self.execute_daemon(config, operator_classes)
+      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+      jobs = filter_since(jobs, source_map, config) if config.since
+
+      abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
+      client = DaemonClient.new(boot: daemon_boot_config(config, abs_tests),
+                                app_root: config.project_root).start
+
+      results = []
+      begin
+        jobs.each_with_index do |(subject, mutation, id), i|
+          source  = source_map[subject.file]
+          mutated = mutation.apply(source)
+          # KTD-8 (carried): skip an invalid mutant tool-side — never ship a payload
+          # that would fail to load and read as a false `killed`.
+          r =
+            if Parser.parse_string(mutated).errors.any?
+              Result.skipped
+            else
+              verdict = client.request(
+                id: i, timeout: config.daemon_timeout || DAEMON_TIMEOUT,
+                payload: { "code" => mutated, "source_file" => File.expand_path(subject.file, config.project_root) },
+                tests: abs_tests
+              )
+              daemon_result(verdict)
+            end
+          results << r.with(subject: subject, mutation: mutation, id: id)
+          break if config.fail_fast && r.survived? # #21: stop at the first survivor
+        end
+      ensure
+        client.quit
+      end
+
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # Default per-mutant timeout on the daemon path. Generous because 2a runs the full
+    # `--test` set per mutant (no coverage narrowing until Phase 2c).
+    DAEMON_TIMEOUT = 60
+
+    # The boot config the daemon needs to boot the app once: where to boot, the test
+    # load roots (so `require "test_helper"` resolves in every fork), framework, and
+    # whether this is Rails.
+    def self.daemon_boot_config(config, abs_tests)
+      {
+        project_root: config.project_root,
+        boot: File.expand_path(config.boot || "config/environment", config.project_root),
+        load_paths: test_load_roots(abs_tests),
+        source_dirs: source_dirs(config), # so the daemon can sweep orphan mutant temps
+        framework: config.framework,
+        rails: config.rails
+      }
+    end
+
+    # Map a daemon verdict string to a Result. The daemon reports the four run-time
+    # states it can decide (KTD-5); pre-fork states (skipped/no_coverage/…) are
+    # resolved tool-side before a request is ever sent.
+    def self.daemon_result(verdict)
+      case verdict
+      when "survived" then Result.survived
+      when "killed"   then Result.killed
+      when "timeout"  then Result.timeout
+      else Result.error("daemon verdict: #{verdict}")
+      end
+    end
+
     # Scan a source once into { line_number => :all | Set[operator_syms] } from
     # inline `# mutineer:disable-line [ops]` markers (RuboCop semantics: the marker
     # sits on the same physical line as the code it silences). A bare marker
@@ -222,6 +381,17 @@ module Mutineer
       warn "[mutineer] RAILS_ENV was unset; defaulting to 'test' for --rails."
     end
 
+    # The unique absolute directories holding the sources — the sweep target for
+    # both orphan mechanisms (in-process mutant tempfiles and external backup
+    # files). Shared so the path-expansion rule can't drift between the two paths.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [Array<String>] unique absolute source directories.
+    def self.source_dirs(config)
+      config.sources.map { |f| File.dirname(File.expand_path(f, config.project_root)) }.uniq
+    end
+
     # Removes stale mutant tempfiles from the given directories.
     #
     # @api private

data/lib/mutineer/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - David Teren
@@ -71,6 +71,10 @@ files:
 - lib/mutineer/cli.rb
 - lib/mutineer/config.rb
 - lib/mutineer/coverage_map.rb
+- lib/mutineer/daemon_client.rb
+- lib/mutineer/daemon_server.rb
+- lib/mutineer/external_backend.rb
+- lib/mutineer/file_swap.rb
 - lib/mutineer/isolation.rb
 - lib/mutineer/minitest_integration.rb
 - lib/mutineer/mutant_id.rb