polyrun 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04bfc3ed1a2c01072864dd179decce4d13c68221bba4da0964f4ea600401b57c
-  data.tar.gz: df02fc828fb8ac8c9cf3792ae08420ee87d328a89d79a7eeec26c9e239506ee4
+  metadata.gz: 7666af9186562083f29dc56e6c867e48b877acdff6ad28ff8c351e8d3c308582
+  data.tar.gz: 503f5435deb22112044f7841a82728e6782a770eb656859419e8412d623dcff0
 SHA512:
-  metadata.gz: 378921ebc46b80562c5ae4bb529a3035eed7366cbfbcffd9a5c4bcb1d18f1c1fe6b737dfcc580c9b7e3fb1ce4360ac9ad04c7a7edbc50e4763a2e5430a61c873
-  data.tar.gz: 552545582ab8c34e1411834d5f5ef6d1b6f1d022ead68746059b709cd04d733c6d778b13621c003ec2f4525367bdb5e849577d109e2e04835fcf9b12407bf2ef
+  metadata.gz: d0d5d248f1e072c446049bafff111db6e29d784a4a0992528214a6e29cca7b156b67144e6b9c22fc71fa9143f110ac443cda2953219aa816c5562d3247b5e02b
+  data.tar.gz: d0be776ce5d4a7a5acacfe237a4d07a47c078562aee6a054fb5b63a31a78e199bc2b5ee276b0a8e77a0f0cacd3e4f03cb72d8fd5037baf782d0efb8a1cdf1b04

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 1.4.1 (2026-04-16)
+
+- Add `polyrun merge-failures` and `run-shards --merge-failures` / `--merge-failures-output` / `--merge-failures-format`; merge per-worker JSONL under `tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl` (or RSpec JSON via `-i`). Run merge after all workers exit, including when a shard failed (`--merge-coverage` still runs only after all shards succeed).
+- Add `Polyrun::Reporting::FailureMerge`, `Polyrun::RSpec.install_failure_fragments!`, and `Polyrun::Reporting::RspecFailureFragmentFormatter`; parent sets `POLYRUN_FAILURE_FRAGMENTS=1` on workers when merge-failures is enabled.
+- Add optional `reporting:` in `polyrun.yml` and `Polyrun::Config#reporting` for merge-failures toggles and paths; honor `POLYRUN_MERGE_FAILURES`, `POLYRUN_MERGED_FAILURES_OUT`, `POLYRUN_MERGED_FAILURES_FORMAT`; set `POLYRUN_MERGED_FAILURES_PATH` for `after_suite` when merge wrote a file.
+- On bad JSONL or non-RSpec JSON, raise `Polyrun::Error` with path and line where applicable; `merge-failures` exits 1 without a full stack trace; a failed merge after successful workers forces `run-shards` exit 1.
+- Fix `run_shards_plan_ready_log` to take `cfg` so debug logging for merge-failures does not raise `NameError`.
+
 ## 1.4.0 (2026-04-16)
 
 - Add `hooks:` in `polyrun.yml` — shell commands for `before_suite` / `after_suite`, `before_shard` / `after_shard`, `before_worker` / `after_worker` (RSpec-style YAML keys `before(:suite)`, `before(:all)`, `before(:each)` accepted). Wire hooks into `run-shards`, `parallel-rspec`, and `ci-shard-*`.

data/lib/polyrun/cli/failure_commands.rb

@@ -0,0 +1,92 @@
+require "json"
+require "fileutils"
+require "optparse"
+
+require_relative "../reporting/failure_merge"
+
+module Polyrun
+  class CLI
+    module FailureCommands
+      private
+
+      def cmd_merge_failures(argv, _config_path)
+        inputs, output, format = merge_failures_parse_argv(argv)
+        if inputs.empty?
+          Polyrun::Log.warn "merge-failures: need at least one existing -i FILE (after glob expansion)"
+          return 2
+        end
+        Polyrun::Log.warn "merge-failures: merging #{inputs.size} fragment(s)" if @verbose
+        n = merge_failures_merge_files_or_warn!(inputs, output: output, format: format)
+        return 1 if n.nil?
+
+        Polyrun::Log.puts File.expand_path(output)
+        Polyrun::Log.warn "merge-failures: #{n} failure row(s)" if @verbose
+        0
+      end
+
+      def merge_failures_merge_files_or_warn!(inputs, output:, format:)
+        Polyrun::Reporting::FailureMerge.merge_files!(inputs, output: output, format: format)
+      rescue Polyrun::Error => e
+        Polyrun::Log.warn e.message.to_s
+        nil
+      end
+
+      def merge_failures_parse_argv(argv)
+        inputs = []
+        output = File.join("tmp", "polyrun_failures", "merged.jsonl")
+        format = "jsonl"
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun merge-failures -i FILE [-i FILE] [-o PATH] [--format jsonl|json]"
+          opts.on("-i", "--input FILE", "JSONL fragment or RSpec JSON (repeatable; globs ok)") do |f|
+            expand_merge_input_pattern(f).each { |x| inputs << x }
+          end
+          opts.on("-o", "--output PATH", String) { |v| output = v }
+          opts.on("--format VAL", "jsonl (default) or json") { |v| format = v }
+        end.parse!(argv)
+        inputs.uniq!
+        inputs.select! { |p| File.file?(p) }
+        [inputs, output, format]
+      end
+
+      # After run-shards workers exit: merge polyrun failure fragments when requested.
+      # Runs even when shards failed (unlike --merge-coverage).
+      # @return [String, nil] absolute path to merged file, or nil when skipped / nothing written
+      def merge_failures_after_shards(ctx)
+        return nil unless ctx[:merge_failures]
+
+        pattern = Polyrun::Reporting::FailureMerge.default_fragment_glob
+        files = Dir.glob(pattern).sort
+        if files.empty?
+          Polyrun::Log.warn "polyrun run-shards: --merge-failures: no #{Polyrun::Reporting::FailureMerge::FRAGMENT_GLOB} under fragment dir (enable Polyrun::RSpec.install_failure_fragments! in spec_helper?)"
+          return nil
+        end
+
+        fmt = merge_failures_resolved_format(ctx)
+        out = merge_failures_resolved_output_path(ctx, fmt)
+        Polyrun::Log.warn "polyrun run-shards: merging #{files.size} failure fragment(s) → #{out} (#{fmt})"
+        Polyrun::Debug.log_kv(merge_failures: "start", output: out, inputs: files, format: fmt)
+        n = Polyrun::Reporting::FailureMerge.merge_files!(files, output: out, format: fmt)
+        Polyrun::Debug.log_kv(merge_failures: "done", rows: n, output: File.expand_path(out))
+        File.expand_path(out)
+      end
+
+      def merge_failures_resolved_format(ctx)
+        f = ctx[:merge_failures_format].to_s.strip.downcase
+        return "jsonl" if f.empty?
+        return "jsonl" if f == "jsonl"
+        return "json" if f == "json"
+
+        Polyrun::Log.warn "polyrun run-shards: unknown merge_failures_format=#{ctx[:merge_failures_format].inspect}; using jsonl"
+        "jsonl"
+      end
+
+      def merge_failures_resolved_output_path(ctx, fmt)
+        raw = ctx[:merge_failures_output]
+        return File.expand_path(raw) if raw && !raw.to_s.strip.empty?
+
+        ext = (fmt == "json") ? "json" : "jsonl"
+        File.expand_path(File.join("tmp", "polyrun_failures", "merged.#{ext}"))
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -21,6 +21,7 @@ module Polyrun
           Skip start auto-prepare / auto DB provision: POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
           Skip writing paths_file from partition.paths_build: POLYRUN_SKIP_PATHS_BUILD=1
           Warn if merge-coverage wall time exceeds N seconds (default 10): POLYRUN_MERGE_SLOW_WARN_SECONDS (0 disables)
+          Failure fragments (run-shards --merge-failures): POLYRUN_MERGE_FAILURES=1; parent sets POLYRUN_FAILURE_FRAGMENTS=1 in workers; POLYRUN_FAILURE_FRAGMENT_DIR, POLYRUN_MERGED_FAILURES_OUT, POLYRUN_MERGED_FAILURES_FORMAT; after_suite sets POLYRUN_MERGED_FAILURES_PATH when merge ran
           Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start); distinct from POLYRUN_SHARD_PROCESSES / ci-shard --shard-processes (local processes per CI matrix job)
           Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
 
@@ -29,7 +30,8 @@ module Polyrun
             plan                 emit partition manifest JSON
             prepare              run prepare recipe: default | assets (optional prepare.command overrides bin/rails assets:precompile) | shell (prepare.command required)
             merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console)
-            run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage
+            merge-failures       merge per-shard failure JSONL fragments or RSpec JSON files (jsonl/json)
+            run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage / --merge-failures
             parallel-rspec       run-shards + merge-coverage (defaults to: bundle exec rspec after --)
             start                parallel-rspec; auto-runs prepare (shell/assets) and db:setup-* when polyrun.yml configures them; legacy script/build_spec_paths.rb if paths_build absent
             ci-shard-run         CI matrix: build-paths + plan for POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL (or config), then run your command with that shard's paths after --; optional --shard-processes M or --workers M (POLYRUN_SHARD_PROCESSES; not POLYRUN_WORKERS) for N×M jobs × processes on this host

data/lib/polyrun/cli/run_shards_command.rb

@@ -2,12 +2,14 @@ require "optparse"
 require "rbconfig"
 
 require_relative "start_bootstrap"
+require_relative "failure_commands"
 require_relative "run_shards_run"
 
 module Polyrun
   class CLI
     module RunShardsCommand
       include StartBootstrap
+      include FailureCommands
       include RunShardsRun
 
       private
@@ -114,10 +116,11 @@ module Polyrun
       # ENV for a worker process: POLYRUN_SHARD_* plus per-shard database URLs from polyrun.yml or DATABASE_URL.
       # When +matrix_total+ > 1 with multiple local workers, sets +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+
       # so {Coverage::Collector} can name fragments uniquely across CI matrix jobs (NxM sharding).
-      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil)
+      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil, failure_fragments: false)
         child_env = ENV.to_h.merge(
           Polyrun::Database::Shard.env_map(shard_index: shard, shard_total: workers)
         )
+        child_env["POLYRUN_FAILURE_FRAGMENTS"] = "1" if failure_fragments
         mt = matrix_total.nil? ? 0 : Integer(matrix_total)
         if mt > 1
           if matrix_index.nil?

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -34,7 +34,14 @@ module Polyrun
             return [pids, code]
           end
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
+          child_env = shard_child_env(
+            cfg: cfg,
+            workers: workers,
+            shard: shard,
+            matrix_index: mx,
+            matrix_total: mt,
+            failure_fragments: ctx[:merge_failures]
+          )
           child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
           child_env = hook_cfg.merge_worker_ruby_env(child_env)
 

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -31,7 +31,7 @@ module Polyrun
         costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])
         return [err, nil] if err
 
-        run_shards_plan_ready_log(o, strategy, cmd, paths_source, items.size)
+        run_shards_plan_ready_log(o, cfg, strategy, cmd, paths_source, items.size)
 
         constraints = load_partition_constraints(pc, o[:constraints_path])
         plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity])
@@ -59,12 +59,13 @@ module Polyrun
         [run_t0, head, cmd, cfg, cfg.partition]
       end
 
-      def run_shards_plan_ready_log(o, strategy, cmd, paths_source, item_count)
+      def run_shards_plan_ready_log(o, cfg, strategy, cmd, paths_source, item_count)
         Polyrun::Debug.log_kv(
           run_shards: "ready to partition",
           workers: o[:workers],
           strategy: strategy,
           merge_coverage: o[:merge_coverage],
+          merge_failures: run_shards_merge_failures_flag(o, cfg),
           command: cmd,
           timing_path: o[:timing_path],
           paths_source: paths_source,
@@ -72,6 +73,37 @@ module Polyrun
         )
       end
 
+      def run_shards_merge_failures_flag(o, cfg)
+        return true if o[:merge_failures]
+        return true if %w[1 true yes].include?(ENV["POLYRUN_MERGE_FAILURES"].to_s.downcase)
+
+        rep = cfg.reporting
+        v = rep["merge_failures"] || rep[:merge_failures]
+        v == true || %w[1 true yes].include?(v.to_s.downcase)
+      end
+
+      def run_shards_merge_failures_output_opt(o, cfg)
+        x = o[:merge_failures_output]
+        return x if x && !x.to_s.strip.empty?
+
+        x = ENV["POLYRUN_MERGED_FAILURES_OUT"]
+        return x if x && !x.to_s.strip.empty?
+
+        rep = cfg.reporting
+        rep["merge_failures_output"] || rep[:merge_failures_output]
+      end
+
+      def run_shards_merge_failures_format_opt(o, cfg)
+        x = o[:merge_failures_format]
+        return x if x && !x.to_s.strip.empty?
+
+        x = ENV["POLYRUN_MERGED_FAILURES_FORMAT"]
+        return x if x && !x.to_s.strip.empty?
+
+        rep = cfg.reporting
+        rep["merge_failures_format"] || rep[:merge_failures_format]
+      end
+
       def run_shards_plan_context_hash(o, cmd, cfg, plan, run_t0, parallel, config_path)
         {
           workers: o[:workers],
@@ -83,6 +115,9 @@ module Polyrun
           merge_coverage: o[:merge_coverage],
           merge_output: o[:merge_output],
           merge_format: o[:merge_format],
+          merge_failures: run_shards_merge_failures_flag(o, cfg),
+          merge_failures_output: run_shards_merge_failures_output_opt(o, cfg),
+          merge_failures_format: run_shards_merge_failures_format_opt(o, cfg),
           config_path: config_path
         }
       end

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -24,7 +24,10 @@ module Polyrun
           timing_granularity: nil,
           merge_coverage: false,
           merge_output: nil,
-          merge_format: nil
+          merge_format: nil,
+          merge_failures: false,
+          merge_failures_output: nil,
+          merge_failures_format: nil
         }
       end
 
@@ -34,8 +37,9 @@ module Polyrun
         end.parse!(head)
       end
 
+      # rubocop:disable Metrics/AbcSize -- one argv block for run-shards
       def run_shards_plan_options_register!(opts, st)
-        opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--] <command> [args...]"
+        opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--merge-failures] [--merge-failures-output P] [--merge-failures-format jsonl|json] [--] <command> [args...]"
         opts.on("--workers N", Integer) { |v| st[:workers] = v }
         opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
         opts.on("--seed VAL") { |v| st[:seed] = v }
@@ -46,7 +50,11 @@ module Polyrun
         opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
         opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
         opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
+        opts.on("--merge-failures", "After all workers exit, merge tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl (use Polyrun::RSpec.install_failure_fragments!)") { st[:merge_failures] = true }
+        opts.on("--merge-failures-output PATH", String) { |v| st[:merge_failures_output] = v }
+        opts.on("--merge-failures-format VAL", "jsonl (default) or json") { |v| st[:merge_failures_format] = v }
       end
+      # rubocop:enable Metrics/AbcSize
     end
   end
 end

data/lib/polyrun/cli/run_shards_run.rb

@@ -25,6 +25,8 @@ module Polyrun
         hook_cfg = Polyrun::Hooks.from_config(ctx[:cfg])
         suite_started = false
         exit_code = 1
+        merged_failures_path = nil
+        merge_failures_errored = false
 
         begin
           env_suite = ENV.to_h.merge(
@@ -60,8 +62,20 @@ module Polyrun
             Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
           end
 
+          if ctx[:merge_failures]
+            begin
+              merged_failures_path = merge_failures_after_shards(ctx)
+            rescue Polyrun::Error => e
+              Polyrun::Log.warn e.message.to_s
+              merge_failures_errored = true
+            end
+          end
+
           if failed.any?
-            run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+            run_shards_log_failed_reruns(
+              failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd],
+              merge_failures: ctx[:merge_failures]
+            )
             exit_code = 1
             exit_code = 1 if wait_hook_err != 0
             return exit_code
@@ -69,13 +83,15 @@ module Polyrun
 
           exit_code = run_shards_merge_or_hint_coverage(ctx)
           exit_code = 1 if wait_hook_err != 0 && exit_code == 0
+          exit_code = 1 if merge_failures_errored && exit_code == 0
           exit_code
         ensure
           if suite_started
             env_after = ENV.to_h.merge(
               "POLYRUN_HOOK_ORCHESTRATOR" => "1",
               "POLYRUN_SHARD_TOTAL" => ctx[:workers].to_s,
-              "POLYRUN_SUITE_EXIT_STATUS" => exit_code.to_s
+              "POLYRUN_SUITE_EXIT_STATUS" => exit_code.to_s,
+              "POLYRUN_MERGED_FAILURES_PATH" => merged_failures_path.to_s
             )
             hook_cfg.run_phase_if_enabled(:after_suite, env_after)
           end
@@ -139,7 +155,7 @@ module Polyrun
         0
       end
 
-      def run_shards_log_failed_reruns(failed, shard_results, plan, parallel, workers, cmd)
+      def run_shards_log_failed_reruns(failed, shard_results, plan, parallel, workers, cmd, merge_failures: false)
         exit_by_shard = shard_results.each_with_object({}) { |r, h| h[r[:shard]] = r[:exitstatus] }
         failed_detail = failed.sort.map { |s| "#{s} (exit #{exit_by_shard[s]})" }.join(", ")
         Polyrun::Log.warn "polyrun run-shards: failed shard(s): #{failed_detail}"
@@ -154,6 +170,9 @@ module Polyrun
           rerun << Shellwords.join(cmd + paths)
           Polyrun::Log.warn "polyrun run-shards: shard #{s} re-run (same spec list, no interleave): #{rerun}"
         end
+        unless merge_failures
+          Polyrun::Log.warn "polyrun run-shards: one merged failure report — use run-shards --merge-failures with Polyrun::RSpec.install_failure_fragments!; POLYRUN_MERGED_FAILURES_PATH is set on after_suite when merge runs."
+        end
       end
     end
   end

data/lib/polyrun/cli.rb

@@ -28,7 +28,7 @@ module Polyrun
 
     # Keep in sync with +dispatch_cli_command_subcommands+ (+when+ branches). Used for implicit path routing.
     DISPATCH_SUBCOMMAND_NAMES = %w[
-      plan prepare merge-coverage report-coverage report-junit report-timing
+      plan prepare merge-coverage merge-failures report-coverage report-junit report-timing
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
       run-shards parallel-rspec start build-paths init queue quick hook
     ].freeze
@@ -145,6 +145,8 @@ module Polyrun
         cmd_prepare(argv, config_path)
       when "merge-coverage"
         cmd_merge_coverage(argv, config_path)
+      when "merge-failures"
+        cmd_merge_failures(argv, config_path)
       when "report-coverage"
         cmd_report_coverage(argv)
       when "report-junit"

data/lib/polyrun/config.rb

@@ -66,6 +66,11 @@ module Polyrun
     def hooks
       raw["hooks"] || raw[:hooks] || {}
     end
+
+    # Optional +reporting:+ block (merge-failures output paths, etc.).
+    def reporting
+      raw["reporting"] || raw[:reporting] || {}
+    end
   end
 end
 

data/lib/polyrun/reporting/failure_merge.rb

@@ -0,0 +1,135 @@
+require "json"
+require "fileutils"
+
+module Polyrun
+  module Reporting
+    # Merge per-worker / per-shard failure fragments (JSONL or RSpec JSON) into one report.
+    # Fragment basenames align with {Coverage::CollectorFragmentMeta} (worker index and optional matrix shard).
+    module FailureMerge
+      DEFAULT_FRAGMENT_DIR = "tmp/polyrun_failures".freeze
+      FRAGMENT_GLOB = "polyrun-failure-fragment-*.jsonl".freeze
+
+      module_function
+
+      def default_fragment_glob(dir = nil)
+        root = File.expand_path(dir || DEFAULT_FRAGMENT_DIR, Dir.pwd)
+        File.join(root, FRAGMENT_GLOB)
+      end
+
+      def merge_fragment_paths(quiet: false)
+        p = default_fragment_glob
+        Dir.glob(p).sort.tap do |paths|
+          Polyrun::Log.warn "merge-failures: no files matched #{p}" if paths.empty? && !quiet
+        end
+      end
+
+      # @param paths [Array<String>] fragment paths (.jsonl and/or RSpec --format json outputs)
+      # @param format [String] "jsonl" or "json"
+      # @param output [String] destination path
+      # @return [Integer] count of failure rows merged
+      def merge_files!(paths, output:, format: "jsonl")
+        fmt = format.to_s.downcase
+        rows = collect_rows(paths)
+        out_abs = File.expand_path(output)
+        FileUtils.mkdir_p(File.dirname(out_abs))
+        case fmt
+        when "json"
+          doc = {
+            "meta" => {
+              "polyrun_merge" => true,
+              "inputs" => paths.map { |p| File.expand_path(p) },
+              "failure_count" => rows.size
+            },
+            "failures" => rows
+          }
+          File.write(out_abs, JSON.generate(doc))
+        when "jsonl"
+          File.write(out_abs, rows.map { |h| JSON.generate(h) }.join("\n") + (rows.empty? ? "" : "\n"))
+        else
+          raise Polyrun::Error, "merge-failures: unknown format #{fmt.inspect} (use jsonl or json)"
+        end
+        rows.size
+      end
+
+      def collect_rows(paths)
+        rows = []
+        paths.each do |p|
+          rows.concat(rows_from_path(p))
+        end
+        rows
+      end
+
+      def rows_from_path(path)
+        ext = File.extname(path).downcase
+        if ext == ".jsonl"
+          return rows_from_jsonl_file(path)
+        end
+
+        text = File.read(path)
+        data =
+          begin
+            JSON.parse(text)
+          rescue JSON::ParserError => e
+            raise Polyrun::Error, "merge-failures: #{path} is not valid JSON: #{e.message}"
+          end
+        if data.is_a?(Hash) && data["examples"].is_a?(Array)
+          return failures_from_rspec_examples(data["examples"])
+        end
+
+        hint =
+          if data.is_a?(Hash)
+            keys = data.keys
+            "got JSON object with keys: #{keys.take(12).join(", ")}" + ((keys.size > 12) ? ", …" : "")
+          else
+            "got #{data.class}"
+          end
+        raise Polyrun::Error,
+          "merge-failures: #{path} is not RSpec JSON (expected top-level \"examples\" array). #{hint}. " \
+          "Use RSpec --format json, or polyrun failure JSONL (.jsonl fragments)."
+      end
+
+      def rows_from_jsonl_file(path)
+        acc = []
+        File.readlines(path, chomp: true).each_with_index do |line, idx|
+          line = line.strip
+          next if line.empty?
+
+          acc << parse_jsonl_line!(path, idx + 1, line)
+        end
+        acc
+      end
+
+      def parse_jsonl_line!(path, line_number, line)
+        JSON.parse(line)
+      rescue JSON::ParserError => e
+        raise Polyrun::Error,
+          "merge-failures: invalid JSONL at #{path} line #{line_number}: #{e.message}"
+      end
+
+      def failures_from_rspec_examples(examples)
+        examples.each_with_object([]) do |ex, acc|
+          next unless ex.is_a?(Hash)
+          next unless ex["status"].to_s == "failed"
+
+          acc << rspec_example_to_row(ex)
+        end
+      end
+
+      def rspec_example_to_row(ex)
+        ex = ex.transform_keys(&:to_s)
+        exc = ex["exception"] || {}
+        exc = exc.transform_keys(&:to_s) if exc.is_a?(Hash)
+        {
+          "id" => ex["id"],
+          "full_description" => ex["full_description"],
+          "location" => (ex["file_path"] && ex["line_number"]) ? "#{ex["file_path"]}:#{ex["line_number"]}" : ex["full_description"],
+          "file_path" => ex["file_path"],
+          "line_number" => ex["line_number"],
+          "message" => exc["message"] || ex["full_description"],
+          "exception_class" => exc["class"],
+          "source" => "rspec_json"
+        }.compact
+      end
+    end
+  end
+end

data/lib/polyrun/reporting/rspec_failure_fragment_formatter.rb

@@ -0,0 +1,95 @@
+require "json"
+require "fileutils"
+
+module Polyrun
+  module Reporting
+    # RSpec formatter: appends one JSON object per failed example to the shard fragment file.
+    # Enable via +Polyrun::RSpec.install_failure_fragments!+ and +POLYRUN_FAILURE_FRAGMENTS=1+ (set by run-shards --merge-failures).
+    #
+    # Output: +tmp/polyrun_failures/polyrun-failure-fragment-<workerN|shardM-workerN>.jsonl+
+    # (same basename rules as {Coverage::CollectorFragmentMeta}.)
+    class RspecFailureFragmentFormatter
+      ::RSpec::Core::Formatters.register self, :start, :example_failed
+
+      attr_reader :output
+
+      def initialize(output)
+        @output = output
+        @path = fragment_path
+      end
+
+      def start(_notification)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, "")
+      end
+
+      def example_failed(notification)
+        ex = notification.example
+        exc = notification.exception
+        row = {
+          "id" => ex.id,
+          "full_description" => ex.full_description,
+          "location" => ex.location,
+          "file_path" => ex.file_path,
+          "line_number" => example_line_number(ex),
+          "message" => exc.message.to_s,
+          "exception_class" => exc.class.name,
+          "polyrun_shard_index" => ENV["POLYRUN_SHARD_INDEX"],
+          "polyrun_shard_total" => ENV["POLYRUN_SHARD_TOTAL"],
+          "polyrun_shard_matrix_index" => matrix_env_or_nil("POLYRUN_SHARD_MATRIX_INDEX"),
+          "polyrun_shard_matrix_total" => matrix_env_or_nil("POLYRUN_SHARD_MATRIX_TOTAL"),
+          "rspec_seed" => seed_if_known,
+          "rspec_order" => order_if_known
+        }
+        trim_backtrace!(row, exc)
+        File.open(@path, "a") { |f| f.puts(JSON.generate(row.compact)) }
+      end
+
+      private
+
+      def example_line_number(ex)
+        return ex.line_number if ex.respond_to?(:line_number)
+
+        ex.metadata[:line_number]
+      end
+
+      def fragment_path
+        dir = ENV.fetch("POLYRUN_FAILURE_FRAGMENT_DIR", FailureMerge::DEFAULT_FRAGMENT_DIR)
+        base = Polyrun::Coverage::CollectorFragmentMeta.fragment_default_basename_from_env
+        File.expand_path(File.join(dir, "polyrun-failure-fragment-#{base}.jsonl"))
+      end
+
+      def matrix_env_or_nil(name)
+        v = ENV[name]
+        return nil if v.nil? || v.to_s.strip.empty?
+
+        v
+      end
+
+      def seed_if_known
+        return unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        ::RSpec.configuration.seed
+      rescue
+        nil
+      end
+
+      def order_if_known
+        return unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        ::RSpec.configuration.order.to_s
+      rescue
+        nil
+      end
+
+      MAX_BT = 20
+
+      def trim_backtrace!(row, exc)
+        bt = exc.backtrace
+        return unless bt.is_a?(Array) && bt.any?
+
+        row["backtrace"] = bt.first(MAX_BT)
+      end
+    end
+  end
+end

data/lib/polyrun/rspec.rb

@@ -30,5 +30,19 @@ module Polyrun
         config.add_formatter fmt
       end
     end
+
+    # Per-worker failure JSONL fragments for +polyrun run-shards --merge-failures+ (parity with coverage shards).
+    # Requires +POLYRUN_FAILURE_FRAGMENTS=1+ (set by the parent when --merge-failures is used) unless +only_if+ overrides.
+    # Writes +tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl+ (override dir with +POLYRUN_FAILURE_FRAGMENT_DIR+).
+    def install_failure_fragments!(only_if: nil)
+      pred = only_if || -> { %w[1 true yes].include?(ENV["POLYRUN_FAILURE_FRAGMENTS"].to_s.downcase) }
+      return unless pred.call
+
+      require "rspec/core"
+      require_relative "reporting/rspec_failure_fragment_formatter"
+      ::RSpec.configure do |config|
+        config.add_formatter Polyrun::Reporting::RspecFailureFragmentFormatter
+      end
+    end
   end
 end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "1.4.0"
+  VERSION = "1.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Andrei Makarov
@@ -175,6 +175,7 @@ files:
 - lib/polyrun/cli/database_commands.rb
 - lib/polyrun/cli/default_run.rb
 - lib/polyrun/cli/env_commands.rb
+- lib/polyrun/cli/failure_commands.rb
 - lib/polyrun/cli/help.rb
 - lib/polyrun/cli/helpers.rb
 - lib/polyrun/cli/hooks_command.rb
@@ -258,8 +259,10 @@ files:
 - lib/polyrun/quick/reporter.rb
 - lib/polyrun/quick/runner.rb
 - lib/polyrun/railtie.rb
+- lib/polyrun/reporting/failure_merge.rb
 - lib/polyrun/reporting/junit.rb
 - lib/polyrun/reporting/junit_emit.rb
+- lib/polyrun/reporting/rspec_failure_fragment_formatter.rb
 - lib/polyrun/reporting/rspec_junit.rb
 - lib/polyrun/rspec.rb
 - lib/polyrun/templates/POLYRUN.md