polyrun 1.2.0 → 1.4.0

data/lib/polyrun/cli/queue_command.rb

@@ -7,11 +7,18 @@ module Polyrun
       private
 
       # File-backed queue (spec_queue.md): init → claim batches → ack (ledger append-only).
+      #
+      # *N×M and load balancing*: +queue init+ uses the same +Partition::Plan+ slice as +polyrun plan+
+      # when +--shard+ / +--total+ (or +partition.shard_index+ / +shard_total+ / CI env) define a matrix.
+      # Each CI job runs +init+ once for its shard; the queue holds **only** that shard's paths (no duplicate
+      # work across matrix jobs). **M** local workers use +queue claim+ on a **shared** queue directory
+      # (NFS or the runner disk): claims are mutually exclusive — **dynamic** balance (fast workers pull more
+      # batches), **not** the same static per-worker wall time as +cost_binpack+ on the full suite.
+      # +--timing+ on init sorts dequeue order (heavy items first when weights are known); it does **not**
+      # replace binpack across workers — for that, use static +plan+ / +run-shards+ with +cost_binpack+.
       def cmd_queue(argv)
         dir = ".polyrun-queue"
         paths_file = nil
-        timing_path = nil
-        timing_granularity = nil
         worker = ENV["USER"] || "worker"
         batch = 5
         lease_id = nil
@@ -20,7 +27,7 @@ module Polyrun
         Polyrun::Debug.log("queue: subcommand=#{sub.inspect}")
         case sub
         when "init"
-          queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
+          queue_cmd_init(argv, dir)
         when "claim"
           queue_cmd_claim(argv, dir, worker, batch)
         when "ack"
@@ -33,34 +40,54 @@ module Polyrun
         end
       end
 
-      def queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
+      def queue_cmd_init(argv, dir)
+        cfg = Polyrun::Config.load(path: ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        ctx = plan_command_initial_context(pc)
+        paths_file = nil
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun queue init --paths-file P [--timing PATH] [--timing-granularity VAL] [--dir DIR]"
+          opts.banner = "usage: polyrun queue init --paths-file P [--dir DIR] [same partition options as polyrun plan]"
           opts.on("--dir PATH") { |v| dir = v }
-          opts.on("--paths-file PATH") { |v| paths_file = v }
-          opts.on("--timing PATH") { |v| timing_path = v }
-          opts.on("--timing-granularity VAL") { |v| timing_granularity = v }
+          opts.on("--paths-file PATH", String) { |v| paths_file = v }
+          plan_command_register_partition_options!(opts, ctx)
         end.parse!(argv)
         unless paths_file
           Polyrun::Log.warn "queue init: need --paths-file"
           return 2
         end
-        cfg = Polyrun::Config.load(path: ENV["POLYRUN_CONFIG"])
-        g = resolve_partition_timing_granularity(cfg.partition, timing_granularity)
-        items = Polyrun::Partition::Paths.read_lines(paths_file)
-        costs =
-          if timing_path
-            Polyrun::Partition::Plan.load_timing_costs(
-              File.expand_path(timing_path, Dir.pwd),
-              granularity: g
-            )
-          end
-        ordered = queue_init_ordered_items(items, costs, g)
+        code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
+        return code if code != 0
+
+        ordered, code = queue_partition_manifest_and_ordered_paths(cfg, pc, ctx, paths_file)
+        return code if code != 0
+
         Polyrun::Queue::FileStore.new(dir).init!(ordered)
         Polyrun::Log.puts JSON.generate({"dir" => File.expand_path(dir), "count" => ordered.size})
         0
       end
 
+      def queue_partition_manifest_and_ordered_paths(cfg, pc, ctx, paths_file)
+        Polyrun::Log.warn "polyrun queue init: using #{cfg.path}" if @verbose && cfg.path
+
+        manifest, code = plan_command_manifest_from_paths(cfg, pc, [], ctx, paths_file)
+        return [nil, code] if code != 0
+
+        paths = manifest["paths"] || []
+        g = resolve_partition_timing_granularity(pc, ctx[:timing_granularity])
+        timing_for_sort = plan_resolve_timing_path(pc, ctx[:timing_path], ctx[:strategy])
+        costs = queue_init_timing_costs(timing_for_sort, g)
+        [queue_init_ordered_items(paths, costs, g), 0]
+      end
+
+      def queue_init_timing_costs(timing_for_sort, g)
+        return nil unless timing_for_sort
+
+        Polyrun::Partition::Plan.load_timing_costs(
+          File.expand_path(timing_for_sort.to_s, Dir.pwd),
+          granularity: g
+        )
+      end
+
       def queue_init_ordered_items(items, costs, granularity = :file)
         if costs && !costs.empty?
           dw = costs.values.sum / costs.size.to_f

data/lib/polyrun/cli/run_shards_command.rb

@@ -15,7 +15,7 @@ module Polyrun
       # Default and upper bound for parallel OS processes (POLYRUN_WORKERS / --workers); see {Polyrun::Config}.
 
       # Spawns N OS processes (not Ruby threads) with POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL so
-      # {Coverage::Collector} writes coverage/polyrun-fragment-<shard>.json. Merge with merge-coverage.
+      # {Coverage::Collector} writes coverage/polyrun-fragment-worker<N>.json (or shard<S>-worker<W>.json in N×M CI). Merge with merge-coverage.
       def cmd_run_shards(argv, config_path)
         run_shards_run!(argv, config_path)
       end
@@ -112,10 +112,21 @@ module Polyrun
       end
 
       # ENV for a worker process: POLYRUN_SHARD_* plus per-shard database URLs from polyrun.yml or DATABASE_URL.
-      def shard_child_env(cfg:, workers:, shard:)
+      # 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)
         child_env = ENV.to_h.merge(
           Polyrun::Database::Shard.env_map(shard_index: shard, shard_total: workers)
         )
+        mt = matrix_total.nil? ? 0 : Integer(matrix_total)
+        if mt > 1
+          if matrix_index.nil?
+            Polyrun::Log.warn "polyrun run-shards: matrix_total=#{mt} but matrix_index is nil; omit POLYRUN_SHARD_MATRIX_*"
+          else
+            child_env["POLYRUN_SHARD_MATRIX_INDEX"] = Integer(matrix_index).to_s
+            child_env["POLYRUN_SHARD_MATRIX_TOTAL"] = mt.to_s
+          end
+        end
         dh = cfg.databases
         if dh.is_a?(Hash) && !dh.empty?
           child_env.merge!(Polyrun::Database::UrlBuilder.env_exports_for_databases(dh, shard_index: shard))

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -0,0 +1,92 @@
+module Polyrun
+  class CLI
+    # Spawns and waits on worker processes for +run-shards+ / +ci-shard-*+ fan-out.
+    module RunShardsParallelChildren
+      private
+
+      # @return [Array(Array, Integer, nil)] +[pids, spawn_error_code]+; +spawn_error_code+ is +nil+ when all spawns succeeded
+      # rubocop:disable Metrics/AbcSize -- shard loop: spawn + shard hooks + env
+      def run_shards_spawn_workers(ctx, hook_cfg)
+        workers = ctx[:workers]
+        cmd = ctx[:cmd]
+        cfg = ctx[:cfg]
+        plan = ctx[:plan]
+        parallel = ctx[:parallel]
+        mx = ctx[:matrix_shard_index]
+        mt = ctx[:matrix_shard_total]
+
+        pids = []
+        workers.times do |shard|
+          paths = plan.shard(shard)
+          if paths.empty?
+            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
+            next
+          end
+
+          env_shard = ENV.to_h.merge(
+            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+            "POLYRUN_SHARD_INDEX" => shard.to_s,
+            "POLYRUN_SHARD_TOTAL" => workers.to_s
+          )
+          code = hook_cfg.run_phase_if_enabled(:before_shard, env_shard)
+          if code != 0
+            run_shards_terminate_children!(pids)
+            return [pids, code]
+          end
+
+          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
+          child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
+          child_env = hook_cfg.merge_worker_ruby_env(child_env)
+
+          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
+          pid = run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+          pids << {pid: pid, shard: shard}
+          Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
+          Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+        end
+        [pids, nil]
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+        if hook_cfg.worker_hooks? && !Polyrun::Hooks.disabled?
+          Process.spawn(child_env, "sh", "-c", hook_cfg.build_worker_shell_script(cmd, paths))
+        else
+          Process.spawn(child_env, *cmd, *paths)
+        end
+      end
+
+      # @return [Array(Array, Integer)] +[shard_results, after_shard_hook_error_code]+ (0 when all +after_shard+ hooks passed)
+      def run_shards_wait_all_children(pids, hook_cfg, ctx)
+        workers = ctx[:workers]
+        shard_results = []
+        after_hook_err = 0
+        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
+          pids.each do |h|
+            Process.wait(h[:pid])
+            exitstatus = $?.exitstatus
+            ok = $?.success?
+            Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
+            env_after = ENV.to_h.merge(
+              "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+              "POLYRUN_SHARD_INDEX" => h[:shard].to_s,
+              "POLYRUN_SHARD_TOTAL" => workers.to_s,
+              "POLYRUN_WORKER_EXIT_STATUS" => exitstatus.to_s
+            )
+            rc = hook_cfg.run_phase_if_enabled(:after_shard, env_after)
+            after_hook_err = rc if rc != 0 && after_hook_err == 0
+            shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
+          end
+        rescue Interrupt
+          # Do not trap SIGINT: Process.wait raises Interrupt; a trap races and prints Interrupt + SystemExit traces.
+          run_shards_shutdown_on_signal!(pids, 130)
+        rescue SignalException => e
+          raise unless e.signm == "SIGTERM"
+
+          run_shards_shutdown_on_signal!(pids, 143)
+        end
+        [shard_results, after_hook_err]
+      end
+    end
+  end
+end

data/lib/polyrun/cli/run_shards_run.rb

@@ -2,12 +2,14 @@ require "shellwords"
 require "rbconfig"
 
 require_relative "run_shards_planning"
+require_relative "run_shards_parallel_children"
 
 module Polyrun
   class CLI
     # Partition + spawn workers for `polyrun run-shards` (keeps {RunShardsCommand} file small).
     module RunShardsRun
       include RunShardsPlanning
+      include RunShardsParallelChildren
 
       private
 
@@ -18,57 +20,68 @@ module Polyrun
         run_shards_workers_and_merge(ctx)
       end
 
+      # rubocop:disable Metrics/AbcSize -- orchestration: hooks, merge, worker failures
       def run_shards_workers_and_merge(ctx)
-        pids = run_shards_spawn_workers(ctx)
-        return 1 if pids.empty?
-
-        run_shards_warn_interleaved(ctx[:parallel], pids.size)
-
-        shard_results = run_shards_wait_all_children(pids)
-        failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
-
-        Polyrun::Debug.log(format(
-          "run-shards: workers wall time since start: %.3fs",
-          Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
-        ))
+        hook_cfg = Polyrun::Hooks.from_config(ctx[:cfg])
+        suite_started = false
+        exit_code = 1
+
+        begin
+          env_suite = ENV.to_h.merge(
+            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+            "POLYRUN_SHARD_TOTAL" => ctx[:workers].to_s
+          )
+          code = hook_cfg.run_phase_if_enabled(:before_suite, env_suite)
+          return code if code != 0
+
+          suite_started = true
+
+          pids, spawn_err = run_shards_spawn_workers(ctx, hook_cfg)
+          if spawn_err
+            exit_code = spawn_err
+            return spawn_err
+          end
+          if pids.empty?
+            exit_code = 1
+            return 1
+          end
 
-        if ctx[:parallel]
-          Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
-        end
+          run_shards_warn_interleaved(ctx[:parallel], pids.size)
 
-        if failed.any?
-          run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
-          return 1
-        end
+          shard_results, wait_hook_err = run_shards_wait_all_children(pids, hook_cfg, ctx)
+          failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
 
-        run_shards_merge_or_hint_coverage(ctx)
-      end
+          Polyrun::Debug.log(format(
+            "run-shards: workers wall time since start: %.3fs",
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
+          ))
 
-      def run_shards_spawn_workers(ctx)
-        workers = ctx[:workers]
-        cmd = ctx[:cmd]
-        cfg = ctx[:cfg]
-        plan = ctx[:plan]
-        parallel = ctx[:parallel]
-
-        pids = []
-        workers.times do |shard|
-          paths = plan.shard(shard)
-          if paths.empty?
-            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
-            next
+          if ctx[:parallel]
+            Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
           end
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard)
+          if failed.any?
+            run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+            exit_code = 1
+            exit_code = 1 if wait_hook_err != 0
+            return exit_code
+          end
 
-          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
-          pid = Process.spawn(child_env, *cmd, *paths)
-          pids << {pid: pid, shard: shard}
-          Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
-          Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+          exit_code = run_shards_merge_or_hint_coverage(ctx)
+          exit_code = 1 if wait_hook_err != 0 && 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
+            )
+            hook_cfg.run_phase_if_enabled(:after_suite, env_after)
+          end
         end
-        pids
       end
+      # rubocop:enable Metrics/AbcSize
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
@@ -77,27 +90,6 @@ module Polyrun
         Polyrun::Log.warn "polyrun run-shards: each worker prints its own summary line; the last \"N examples\" line is not a total across shards."
       end
 
-      def run_shards_wait_all_children(pids)
-        shard_results = []
-        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
-          pids.each do |h|
-            Process.wait(h[:pid])
-            exitstatus = $?.exitstatus
-            ok = $?.success?
-            Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
-            shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
-          end
-        rescue Interrupt
-          # Do not trap SIGINT: Process.wait raises Interrupt; a trap races and prints Interrupt + SystemExit traces.
-          run_shards_shutdown_on_signal!(pids, 130)
-        rescue SignalException => e
-          raise unless e.signm == "SIGTERM"
-
-          run_shards_shutdown_on_signal!(pids, 143)
-        end
-        shard_results
-      end
-
       # Best-effort worker teardown then exit. Does not return.
       def run_shards_shutdown_on_signal!(pids, code)
         run_shards_terminate_children!(pids)
@@ -140,7 +132,7 @@ module Polyrun
 
         if ctx[:parallel]
           Polyrun::Log.warn <<~MSG
-            polyrun run-shards: coverage — each worker writes coverage/polyrun-fragment-<shard>.json when Polyrun coverage is enabled (POLYRUN_SHARD_INDEX per process).
+            polyrun run-shards: coverage — each worker writes coverage/polyrun-fragment-worker<N>.json when Polyrun coverage is enabled (POLYRUN_SHARD_INDEX per process).
             polyrun run-shards: next step — merge with: polyrun merge-coverage -i 'coverage/polyrun-fragment-*.json' -o coverage/merged.json --format json,cobertura,console
           MSG
         end

data/lib/polyrun/cli.rb

@@ -12,9 +12,11 @@ require_relative "cli/queue_command"
 require_relative "cli/timing_command"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
+require_relative "cli/ci_shard_run_parse"
 require_relative "cli/ci_shard_run_command"
 require_relative "cli/config_command"
 require_relative "cli/default_run"
+require_relative "cli/hooks_command"
 require_relative "cli/help"
 
 module Polyrun
@@ -28,7 +30,7 @@ module Polyrun
     DISPATCH_SUBCOMMAND_NAMES = %w[
       plan prepare merge-coverage 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
+      run-shards parallel-rspec start build-paths init queue quick hook
     ].freeze
 
     # First argv token that is a normal subcommand (not a path); if argv[0] is not here but looks like paths, run implicit parallel.
@@ -48,9 +50,11 @@ module Polyrun
     include TimingCommand
     include InitCommand
     include QuickCommand
+    include CiShardRunParse
     include CiShardRunCommand
     include ConfigCommand
     include DefaultRun
+    include HooksCommand
     include Help
 
     def self.run(argv = ARGV)
@@ -175,6 +179,8 @@ module Polyrun
         cmd_queue(argv)
       when "quick"
         cmd_quick(argv)
+      when "hook"
+        cmd_hook(argv, config_path)
       else
         Polyrun::Log.warn "unknown command: #{command}"
         2

data/lib/polyrun/config/effective.rb

@@ -4,7 +4,7 @@ require_relative "resolver"
 module Polyrun
   class Config
     # Nested hash of values Polyrun uses: loaded YAML (string keys) with overlays for
-    # merged +prepare.env+, resolved +partition.shard_index+ / +shard_total+ / +timing_granularity+,
+    # merged +prepare.env+, resolved +partition.shard_index+ / +shard_total+ / +shard_processes+ / +timing_granularity+,
     # and top-level +workers+ (+POLYRUN_WORKERS+ default).
     #
     # +build+ memoizes the last (cfg, env) in-process so repeated +dig+ calls on the same load do not
@@ -44,6 +44,7 @@ module Polyrun
           part = deep_stringify_keys(pc).merge(
             "shard_index" => r.resolve_shard_index(pc, env),
             "shard_total" => r.resolve_shard_total(pc, env),
+            "shard_processes" => r.resolve_shard_processes(pc, env),
             "timing_granularity" => r.resolve_partition_timing_granularity(pc, nil, env).to_s
           )
           base["partition"] = part

data/lib/polyrun/config/resolver.rb

@@ -54,6 +54,14 @@ module Polyrun
         partition_int(pc, %w[shard_total total], 1)
       end
 
+      # Processes per CI matrix job for +ci-shard-run+ / +ci-shard-rspec+ (NxM: N jobs × M processes).
+      # +POLYRUN_SHARD_PROCESSES+ or +partition.shard_processes+; CLI +--shard-processes+ / +--workers+ overrides.
+      def resolve_shard_processes(pc, env = ENV)
+        return Integer(env["POLYRUN_SHARD_PROCESSES"]) if env["POLYRUN_SHARD_PROCESSES"] && !env["POLYRUN_SHARD_PROCESSES"].empty?
+
+        partition_int(pc, %w[shard_processes shard_workers workers_per_shard], 1)
+      end
+
       # +cli_val+ is an override (e.g. +run-shards --timing-granularity+); +nil+ uses YAML then +POLYRUN_TIMING_GRANULARITY+.
       def resolve_partition_timing_granularity(pc, cli_val, env = ENV)
         raw = cli_val

data/lib/polyrun/config.rb

@@ -61,6 +61,11 @@ module Polyrun
     def version
       raw["version"] || raw[:version]
     end
+
+    # Optional +hooks:+ block for +run-shards+ / +parallel-rspec+ / +ci-shard-*+ (see {Hooks}).
+    def hooks
+      raw["hooks"] || raw[:hooks] || {}
+    end
   end
 end
 

data/lib/polyrun/coverage/collector.rb

@@ -8,6 +8,7 @@ require_relative "formatter"
 require_relative "merge"
 require_relative "result"
 require_relative "track_files"
+require_relative "collector_fragment_meta"
 require_relative "../debug"
 
 module Polyrun
@@ -24,7 +25,7 @@ module Polyrun
 
       # @param root [String] project root (absolute or relative)
       # @param reject_patterns [Array<String>] path substrings to drop (like SimpleCov add_filter)
-      # @param output_path [String, nil] default coverage/polyrun-fragment-<shard>.json
+      # @param output_path [String, nil] default see {.fragment_default_basename_from_env}
       # @param minimum_line_percent [Float, nil] exit 1 if below (when strict)
       # @param strict [Boolean] whether to exit non-zero on threshold failure (default true when minimum set)
       # @param track_under [Array<String>] when +track_files+ is nil, only keep coverage keys under these dirs relative to +root+. Default +["lib"]+.
@@ -34,18 +35,25 @@ module Polyrun
       # @param formatter [Object, nil] Object responding to +format(result, output_dir:, basename:)+ like SimpleCov formatters (e.g. {Formatter.multi} or {Formatter::MultiFormatter})
       # @param report_output_dir [String, nil] directory for +formatter+ outputs (default +coverage/+ under +root+)
       # @param report_basename [String] file prefix for formatter outputs (default +polyrun-coverage+)
+      # See {CollectorFragmentMeta.fragment_default_basename_from_env}.
+      def self.fragment_default_basename_from_env(env = ENV)
+        CollectorFragmentMeta.fragment_default_basename_from_env(env)
+      end
+
       def start!(root:, reject_patterns: [], track_under: ["lib"], track_files: nil, groups: nil, output_path: nil, minimum_line_percent: nil, strict: nil, meta: {}, formatter: nil, report_output_dir: nil, report_basename: "polyrun-coverage")
         return if disabled?
 
         root = File.expand_path(root)
-        shard = ENV.fetch("POLYRUN_SHARD_INDEX", "0")
-        output_path ||= File.join(root, "coverage", "polyrun-fragment-#{shard}.json")
+        basename = fragment_default_basename_from_env
+        output_path ||= File.join(root, "coverage", "polyrun-fragment-#{basename}.json")
         strict = if minimum_line_percent.nil?
           false
         else
           strict.nil? || strict
         end
 
+        fragment_meta = CollectorFragmentMeta.fragment_meta_from_env(basename)
+
         @config = {
           root: root,
           track_under: Array(track_under).map(&:to_s),
@@ -59,7 +67,8 @@ module Polyrun
           formatter: formatter,
           report_output_dir: report_output_dir,
           report_basename: report_basename,
-          shard_total_at_start: ENV["POLYRUN_SHARD_TOTAL"].to_i
+          shard_total_at_start: ENV["POLYRUN_SHARD_TOTAL"].to_i,
+          fragment_meta: fragment_meta
         }
 
         unless ::Coverage.running?
@@ -110,11 +119,7 @@ module Polyrun
       end
 
       def self.finish_debug_time_label
-        if ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
-          "worker pid=#{$$} shard=#{ENV.fetch("POLYRUN_SHARD_INDEX", "?")} Coverage::Collector.finish (write fragment)"
-        else
-          "Coverage::Collector.finish (write fragment)"
-        end
+        CollectorFragmentMeta.finish_debug_time_label
       end
 
       def build_meta(cfg)
@@ -123,6 +128,7 @@ module Polyrun
         m["timestamp"] ||= Time.now.to_i
         m["command_name"] ||= "rspec"
         m["polyrun_coverage_root"] = cfg[:root].to_s
+        CollectorFragmentMeta.merge_fragment_meta!(m, cfg[:fragment_meta])
         if cfg[:groups]
           m["polyrun_coverage_groups"] = cfg[:groups].transform_keys(&:to_s).transform_values(&:to_s)
         end

data/lib/polyrun/coverage/collector_finish.rb

@@ -12,6 +12,8 @@ module Polyrun
           collector_finish: "start",
           polyrun_shard_index: ENV["POLYRUN_SHARD_INDEX"],
           polyrun_shard_total: ENV["POLYRUN_SHARD_TOTAL"],
+          polyrun_shard_matrix_index: ENV["POLYRUN_SHARD_MATRIX_INDEX"],
+          polyrun_shard_matrix_total: ENV["POLYRUN_SHARD_MATRIX_TOTAL"],
           output_path: cfg[:output_path]
         )
         Polyrun::Debug.time(Collector.finish_debug_time_label) do

data/lib/polyrun/coverage/collector_fragment_meta.rb

@@ -0,0 +1,57 @@
+module Polyrun
+  module Coverage
+    # Shard / worker naming for coverage JSON fragments (N×M CI vs run-shards).
+    module CollectorFragmentMeta
+      module_function
+
+      # Default fragment basename (no extension) for +coverage/polyrun-fragment-<basename>.json+.
+      def fragment_default_basename_from_env(env = ENV)
+        local = env.fetch("POLYRUN_SHARD_INDEX", "0")
+        mt = env["POLYRUN_SHARD_MATRIX_TOTAL"].to_i
+        if mt > 1
+          mi = env.fetch("POLYRUN_SHARD_MATRIX_INDEX", "0")
+          "shard#{mi}-worker#{local}"
+        elsif env["POLYRUN_SHARD_TOTAL"].to_i > 1
+          "worker#{local}"
+        else
+          local
+        end
+      end
+
+      def finish_debug_time_label
+        mt = ENV["POLYRUN_SHARD_MATRIX_TOTAL"].to_i
+        if mt > 1
+          "worker pid=#{$$} shard(matrix)=#{ENV.fetch("POLYRUN_SHARD_MATRIX_INDEX", "?")} worker(local)=#{ENV.fetch("POLYRUN_SHARD_INDEX", "?")} Coverage::Collector.finish (write fragment)"
+        elsif ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
+          "worker pid=#{$$} worker=#{ENV.fetch("POLYRUN_SHARD_INDEX", "?")} Coverage::Collector.finish (write fragment)"
+        else
+          "Coverage::Collector.finish (write fragment)"
+        end
+      end
+
+      def fragment_meta_from_env(basename)
+        mt = ENV["POLYRUN_SHARD_MATRIX_TOTAL"].to_i
+        {
+          basename: basename,
+          worker_index: ENV.fetch("POLYRUN_SHARD_INDEX", "0"),
+          shard_matrix_index: shard_matrix_index_value(mt)
+        }
+      end
+
+      def shard_matrix_index_value(matrix_total)
+        return nil if matrix_total <= 1
+
+        ENV.fetch("POLYRUN_SHARD_MATRIX_INDEX", "0")
+      end
+
+      def merge_fragment_meta!(m, fm)
+        return m if fm.nil?
+
+        m["polyrun_fragment_basename"] = fm[:basename].to_s if fm[:basename]
+        m["polyrun_worker_index"] = fm[:worker_index].to_s if fm[:worker_index]
+        m["polyrun_shard_matrix_index"] = fm[:shard_matrix_index].to_s if fm[:shard_matrix_index]
+        m
+      end
+    end
+  end
+end