polyrun 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd8b178e07e0cf6648284d59d5b8f58a5feceeb2c7570edfd381aafaed207cb
-  data.tar.gz: cd2846dc77b56bccf0ac411fcc4f6a2a7aaf2e106609172e84299c2a1d253f64
+  metadata.gz: e3162ed760c231d4fa78ff396f55f708af13bda62808ba340f3c1494cf2dd97e
+  data.tar.gz: f401bd075462bafa14905c08a996fa46370025be9872f6a4d7aefbfdde251d2d
 SHA512:
-  metadata.gz: c9a71f317d28ce3dcdf25d9c8e08221e71eadb2cf044217170ca0ba08cdc22cb702e6adaf02383d4e6089fa2fdddc94198cc420f031f53186715b67c14c92567
-  data.tar.gz: 81469ea975e78befbf6c66e3482e5c6006c11bb8b1806a079545a00ac057f250d49323aeab6685e8eaec22ff65e5aa72fb28aaca688365048483650d3c78de00
+  metadata.gz: 3d0bf0e8ac88d3d0a007f53ce340c324bcd65c6397b4b67905d428d104ebff3078bc41220873b0b7d741e6cc65be06d5d103f8b8abd64e18ce0dc2d8f3e55bc1
+  data.tar.gz: 42906169eeeae14b3531d870359ce8fe9bd59261770553a6e7e6872e48e47b7b1013709eedea5c176a94ccee5c1e498551e8d6285ffc68b37c51d05169b184b1

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## 1.3.0 (2026-04-15)
+
+- Add safe parsing for `ci-shard-run` / `ci-shard-rspec` `--shard-processes` and `--workers` (warn + exit 2 on missing or non-integer values).
+- Fix `shard_child_env` when `matrix_total > 1` and `matrix_index` is nil: omit `POLYRUN_SHARD_MATRIX_*` and warn (avoid `Integer(nil)`).
+- Document in `polyrun help` that `POLYRUN_SHARD_PROCESSES` and ci-shard `--workers` / `--shard-processes` are local processes per matrix job, distinct from `POLYRUN_WORKERS` / `run-shards`.
+- BREAKING: Multi-worker shard runs may emit coverage JSON fragments whose basenames include `shard*` and `worker*` segments; `merge-coverage` still matches `polyrun-fragment-*.json`.
+
 ## 1.2.0 (2026-04-15)
 
 - Add `polyrun config <dotted.path>` to print values from `Polyrun::Config::Effective` (same effective tree as runtime: arbitrary YAML paths, merged `prepare.env.<KEY>` as for `polyrun prepare`, resolved `partition.shard_index`, `partition.shard_total`, `partition.timing_granularity`, and `workers`).

data/lib/polyrun/cli/ci_shard_run_command.rb

@@ -6,6 +6,11 @@ module Polyrun
     # workers on a single host. Runs +build-paths+, +plan+ for that shard, then +exec+ of a user command
     # with that shard's paths appended (same argv pattern as +run-shards+ after +--+).
     #
+    # With +--shard-processes M+ (or +partition.shard_processes+ / +POLYRUN_SHARD_PROCESSES+), fans out
+    # +M+ OS processes on this host, each running a subset of this shard's paths (NxM: +N+ matrix jobs × +M+
+    # processes). Child processes get local +POLYRUN_SHARD_INDEX+ / +POLYRUN_SHARD_TOTAL+ (+0..M-1+, +M+);
+    # when +N+ > 1, also +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+ for unique coverage fragments.
+    #
     # After +--+, prefer **multiple argv tokens** (+bundle+, +exec+, +rspec+, …). A single token that
     # contains spaces is split with +Shellwords+ (not a full shell); exotic quoting differs from +sh -c+.
     module CiShardRunCommand
@@ -25,6 +30,60 @@ module Polyrun
         [paths, 0]
       end
 
+      def ci_shard_local_plan!(paths, workers)
+        Polyrun::Partition::Plan.new(
+          items: paths,
+          total_shards: workers,
+          strategy: "round_robin",
+          root: Dir.pwd
+        )
+      end
+
+      # When +N+ > 1 and +M+ > 1, pass matrix index/total for coverage fragment names; else nil (see +shard_child_env+).
+      def ci_shard_matrix_context(pc, shard_processes)
+        n = resolve_shard_total(pc)
+        return [nil, nil] if n <= 1 || shard_processes <= 1
+
+        [resolve_shard_index(pc), n]
+      end
+
+      def ci_shard_run_fanout!(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] }
+
+        if failed.any?
+          Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (some failed)"
+          run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+          return 1
+        end
+
+        Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (exit 0)"
+        0
+      end
+
+      def ci_shard_fanout_context(cfg:, pc:, paths:, shard_processes:, cmd:, config_path:)
+        plan = ci_shard_local_plan!(paths, shard_processes)
+        mx, mt = ci_shard_matrix_context(pc, shard_processes)
+        {
+          workers: shard_processes,
+          cmd: cmd,
+          cfg: cfg,
+          plan: plan,
+          run_t0: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          parallel: true,
+          merge_coverage: false,
+          merge_output: nil,
+          merge_format: nil,
+          config_path: config_path,
+          matrix_shard_index: mx,
+          matrix_shard_total: mt
+        }
+      end
+
       # Runner-agnostic matrix shard: +polyrun ci-shard-run [plan options] -- <command> [args...]+
       # Paths for this shard are appended after the command (like +run-shards+).
       def cmd_ci_shard_run(argv, config_path)
@@ -42,10 +101,27 @@ module Polyrun
         end
         cmd = Shellwords.split(cmd.first) if cmd.size == 1 && cmd.first.include?(" ")
 
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
         paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-run")
         return code if code != 0
 
-        exec(*cmd, *paths)
+        if shard_processes <= 1
+          exec(*cmd, *paths)
+          return 0
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-run: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
       end
 
       # Same as +ci-shard-run -- bundle exec rspec+ with an optional second segment for RSpec-only flags:
@@ -55,10 +131,29 @@ module Polyrun
         plan_argv = sep ? argv[0...sep] : argv
         rspec_argv = sep ? argv[(sep + 1)..] : []
 
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
         paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-rspec")
         return code if code != 0
 
-        exec("bundle", "exec", "rspec", *rspec_argv, *paths)
+        cmd = ["bundle", "exec", "rspec", *rspec_argv]
+
+        if shard_processes <= 1
+          exec(*cmd, *paths)
+          return 0
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-rspec: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
       end
     end
   end

data/lib/polyrun/cli/ci_shard_run_parse.rb

@@ -0,0 +1,68 @@
+module Polyrun
+  class CLI
+    # Parsing for +ci-shard-run+ / +ci-shard-rspec+ plan argv (+--shard-processes+, +--workers+).
+    module CiShardRunParse
+      private
+
+      # Strips +--shard-processes+ / +--workers+ from +plan_argv+ and returns +[count, exit_code]+.
+      # +exit_code+ is +nil+ on success, +2+ on invalid or missing integer (no exception).
+      # Does not use +OptionParser+ so +plan+ flags (+--shard+, +--total+, …) pass through unchanged.
+      # Note: +--workers+ here means processes for this matrix job (+POLYRUN_SHARD_PROCESSES+), not +run-shards+ +POLYRUN_WORKERS+.
+      def ci_shard_parse_shard_processes!(plan_argv, pc)
+        workers = Polyrun::Config::Resolver.resolve_shard_processes(pc)
+        rest = []
+        i = 0
+        while i < plan_argv.size
+          case plan_argv[i]
+          when "--shard-processes"
+            n, err = ci_shard_parse_positive_int_flag!(plan_argv, i, "--shard-processes")
+            return [nil, err] if err
+
+            workers = n
+            i += 2
+          when "--workers"
+            n, err = ci_shard_parse_positive_int_flag!(plan_argv, i, "--workers")
+            return [nil, err] if err
+
+            workers = n
+            i += 2
+          else
+            rest << plan_argv[i]
+            i += 1
+          end
+        end
+        plan_argv.replace(rest)
+        [workers, nil]
+      end
+
+      # @return [Array(Integer or nil, Integer or nil)] +[value, exit_code]+ — +exit_code+ is +nil+ on success, +2+ on error
+      def ci_shard_parse_positive_int_flag!(argv, i, flag_name)
+        arg = argv[i + 1]
+        if arg.nil?
+          Polyrun::Log.warn "polyrun ci-shard: missing value for #{flag_name}"
+          return [nil, 2]
+        end
+        n = Integer(arg, exception: false)
+        if n.nil?
+          Polyrun::Log.warn "polyrun ci-shard: #{flag_name} must be an integer (got #{arg.inspect})"
+          return [nil, 2]
+        end
+        [n, nil]
+      end
+
+      # @return [Array(Integer, Integer, nil)] +[capped_workers, exit_code]+ — +exit_code+ is +nil+ when OK
+      def ci_shard_normalize_shard_processes(workers)
+        if workers < 1
+          Polyrun::Log.warn "polyrun ci-shard: --shard-processes / --workers must be >= 1"
+          return [workers, 2]
+        end
+        w = workers
+        if w > Polyrun::Config::MAX_PARALLEL_WORKERS
+          Polyrun::Log.warn "polyrun ci-shard: capping --shard-processes / --workers from #{w} to #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
+          w = Polyrun::Config::MAX_PARALLEL_WORKERS
+        end
+        [w, nil]
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -21,7 +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)
-          Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start)
+          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)
 
           commands:
@@ -32,11 +32,11 @@ module Polyrun
             run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage
             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 -- (like run-shards; not multi-worker)
-            ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional -- [rspec-only flags]
+            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
+            ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional --shard-processes / --workers / -- [rspec-only flags]
             build-paths          write partition.paths_file from partition.paths_build (same as auto step before plan/run-shards)
             init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
-            queue                file-backed batch queue (init / claim / ack / status)
+            queue                file-backed batch queue: init (optional --shard/--total etc. as plan, then claim/ack); M workers share one dir; no duplicate paths across claims
             quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
             report-coverage      write all coverage formats from one JSON file
             report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)

data/lib/polyrun/cli/plan_command.rb

@@ -76,21 +76,31 @@ module Polyrun
         }
       end
 
+      # Partition flags shared by +polyrun plan+ and +queue init+ (excluding +--paths-file+, which each command registers once).
+      def plan_command_register_partition_options!(opts, ctx)
+        opts.on("--shard INDEX", Integer) { |v| ctx[:shard] = v }
+        opts.on("--total N", Integer) { |v| ctx[:total] = v }
+        opts.on("--strategy NAME", String) { |v| ctx[:strategy] = v }
+        opts.on("--seed VAL") { |v| ctx[:seed] = v }
+        opts.on("--constraints PATH", "YAML: pin / serial_glob (see spec_queue.md)") { |v| ctx[:constraints_path] = v }
+        opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
+          ctx[:timing_path] = v
+        end
+        opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
+          ctx[:timing_granularity] = v
+        end
+      end
+
+      # Shared by +polyrun plan+ and +queue init+ so partition flags match +Partition::Plan+ / +plan+ JSON.
+      def plan_command_register_options!(opts, ctx)
+        opts.on("--paths-file PATH", String) { |v| ctx[:paths_file] = v }
+        plan_command_register_partition_options!(opts, ctx)
+      end
+
       def plan_command_parse_argv!(argv, ctx)
         OptionParser.new do |opts|
           opts.banner = "usage: polyrun plan [options] [--] [paths...]"
-          opts.on("--shard INDEX", Integer) { |v| ctx[:shard] = v }
-          opts.on("--total N", Integer) { |v| ctx[:total] = v }
-          opts.on("--strategy NAME", String) { |v| ctx[:strategy] = v }
-          opts.on("--seed VAL") { |v| ctx[:seed] = v }
-          opts.on("--paths-file PATH", String) { |v| ctx[:paths_file] = v }
-          opts.on("--constraints PATH", "YAML: pin / serial_glob (see spec_queue.md)") { |v| ctx[:constraints_path] = v }
-          opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
-            ctx[:timing_path] = v
-          end
-          opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
-            ctx[:timing_granularity] = v
-          end
+          plan_command_register_options!(opts, ctx)
         end.parse!(argv)
       end
 

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_run.rb

@@ -50,6 +50,8 @@ module Polyrun
         cfg = ctx[:cfg]
         plan = ctx[:plan]
         parallel = ctx[:parallel]
+        mx = ctx[:matrix_shard_index]
+        mt = ctx[:matrix_shard_total]
 
         pids = []
         workers.times do |shard|
@@ -59,7 +61,7 @@ module Polyrun
             next
           end
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard)
+          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
 
           Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
           pid = Process.spawn(child_env, *cmd, *paths)
@@ -140,7 +142,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,6 +12,7 @@ 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"
@@ -48,6 +49,7 @@ module Polyrun
     include TimingCommand
     include InitCommand
     include QuickCommand
+    include CiShardRunParse
     include CiShardRunCommand
     include ConfigCommand
     include DefaultRun

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/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

data/lib/polyrun/templates/ci_matrix.polyrun.yml

@@ -3,8 +3,9 @@
 #   bundle exec polyrun -c polyrun.yml ci-shard-run -- bundle exec rspec
 # (or ci-shard-rspec; or e.g. ci-shard-run -- bundle exec polyrun quick).
 # Equivalent to build-paths, plan --shard/--total, then run that command with this slice's paths.
-# A separate CI job downloads coverage/polyrun-fragment-*.json and runs merge-coverage.
-# Do not use parallel-rspec with multiple workers inside the same matrix row unless you intend nested parallelism.
+# A separate CI job downloads coverage/polyrun-fragment-*.json (e.g. shard<S>-worker<W>.json per N×M process) and runs merge-coverage.
+# For N×M (N matrix jobs × M processes per job): set shard_processes: M or POLYRUN_SHARD_PROCESSES,
+# or pass --shard-processes M to ci-shard-run / ci-shard-rspec (local split is round-robin).
 # See: docs/SETUP_PROFILE.md
 
 partition:

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -167,6 +167,7 @@ files:
 - lib/polyrun.rb
 - lib/polyrun/cli.rb
 - lib/polyrun/cli/ci_shard_run_command.rb
+- lib/polyrun/cli/ci_shard_run_parse.rb
 - lib/polyrun/cli/config_command.rb
 - lib/polyrun/cli/coverage_commands.rb
 - lib/polyrun/cli/coverage_merge_io.rb
@@ -196,6 +197,7 @@ files:
 - lib/polyrun/coverage/cobertura_zero_lines.rb
 - lib/polyrun/coverage/collector.rb
 - lib/polyrun/coverage/collector_finish.rb
+- lib/polyrun/coverage/collector_fragment_meta.rb
 - lib/polyrun/coverage/filter.rb
 - lib/polyrun/coverage/formatter.rb
 - lib/polyrun/coverage/merge.rb