polyrun 1.4.2 → 2.1.0

data/lib/polyrun/cli/run_shards_command.rb

@@ -3,6 +3,7 @@ require "rbconfig"
 
 require_relative "start_bootstrap"
 require_relative "failure_commands"
+require_relative "spec_quality_commands"
 require_relative "run_shards_run"
 
 module Polyrun
@@ -10,6 +11,7 @@ module Polyrun
     module RunShardsCommand
       include StartBootstrap
       include FailureCommands
+      include SpecQualityCommands
       include RunShardsRun
 
       private
@@ -116,11 +118,13 @@ 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, failure_fragments: false)
+      # rubocop:disable Metrics/AbcSize -- shard ENV: matrix, DB URLs, fragment flags
+      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil, failure_fragments: false, spec_quality_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
+        child_env["POLYRUN_SPEC_QUALITY_FRAGMENTS"] = "1" if spec_quality_fragments
         mt = matrix_total.nil? ? 0 : Integer(matrix_total)
         if mt > 1
           if matrix_index.nil?
@@ -138,6 +142,7 @@ module Polyrun
         end
         child_env
       end
+      # rubocop:enable Metrics/AbcSize
 
       def cmd_build_paths(config_path)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -1,7 +1,13 @@
+require "fileutils"
+
+require_relative "run_shards_parallel_wait"
+
 module Polyrun
   class CLI
-    # Spawns and waits on worker processes for +run-shards+ / +ci-shard-*+ fan-out.
+    # Spawns worker processes for +run-shards+ / +ci-shard-*+ fan-out. See {RunShardsParallelWait} for wait/timeout.
     module RunShardsParallelChildren
+      include RunShardsParallelWait
+
       private
 
       # @return [Array(Array, Integer, nil)] +[pids, spawn_error_code]+; +spawn_error_code+ is +nil+ when all spawns succeeded
@@ -40,14 +46,18 @@ module Polyrun
             shard: shard,
             matrix_index: mx,
             matrix_total: mt,
-            failure_fragments: ctx[:merge_failures]
+            failure_fragments: ctx[:merge_failures],
+            spec_quality_fragments: ctx[:merge_spec_quality]
           )
           child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
           child_env = hook_cfg.merge_worker_ruby_env(child_env)
 
+          ping_path = run_shards_prepare_worker_ping!(ctx, child_env, shard)
+
           Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
+          spawned_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           pid = run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
-          pids << {pid: pid, shard: shard}
+          pids << {pid: pid, shard: shard, spawned_at: spawned_at, ping_path: ping_path}
           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
@@ -55,6 +65,21 @@ module Polyrun
       end
       # rubocop:enable Metrics/AbcSize
 
+      def run_shards_prepare_worker_ping!(ctx, child_env, shard)
+        idle_sec = ctx[:worker_idle_timeout_sec]
+        idle_sec = nil if idle_sec.is_a?(Numeric) && idle_sec <= 0
+        return nil unless idle_sec
+
+        dir = File.join(Dir.pwd, "tmp", "polyrun")
+        FileUtils.mkdir_p(dir)
+        path = File.expand_path("worker-ping-#{$$}-#{shard}.txt", dir)
+        File.binwrite(path, "")
+        child_env["POLYRUN_WORKER_PING_FILE"] = path
+        interval = ENV["POLYRUN_WORKER_PING_INTERVAL_SEC"].to_s.strip
+        child_env["POLYRUN_WORKER_PING_INTERVAL_SEC"] = interval.empty? ? "15" : interval
+        path
+      end
+
       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))
@@ -62,38 +87,6 @@ module Polyrun
           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_parallel_wait.rb

@@ -0,0 +1,267 @@
+# rubocop:disable Polyrun/FileLength, Metrics/ModuleLength -- wait loop + idle/wall flush (kept out of spawn module)
+module Polyrun
+  class CLI
+    # Wait, wall/idle timeout, and +after_shard+ hooks for parallel workers (+run-shards+ / +ci-shard-*+).
+    module RunShardsParallelWait
+      WORKER_TIMEOUT_EXIT_STATUS = 124
+      WORKER_IDLE_TIMEOUT_EXIT_STATUS = 125
+
+      private
+
+      # @return [Array(Array, Integer)] +[shard_results, after_shard_hook_error_code]+ (0 when all +after_shard+ hooks passed)
+      # rubocop:disable Metrics/AbcSize -- wait loop + timeout flush
+      def run_shards_wait_all_children(pids, hook_cfg, ctx)
+        workers = ctx[:workers]
+        shard_results = []
+        after_hook_err = 0
+        timeout_sec = ctx[:worker_timeout_sec]
+        timeout_sec = nil if timeout_sec.is_a?(Numeric) && timeout_sec <= 0
+        idle_sec = ctx[:worker_idle_timeout_sec]
+        idle_sec = nil if idle_sec.is_a?(Numeric) && idle_sec <= 0
+
+        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
+          if timeout_sec || idle_sec
+            run_shards_wait_all_children_multiplex(
+              pids, hook_cfg, ctx, workers, timeout_sec, idle_sec, shard_results, after_hook_err
+            )
+          else
+            run_shards_wait_all_children_sequential(pids, hook_cfg, workers, shard_results, after_hook_err)
+          end
+        rescue Interrupt
+          run_shards_shutdown_on_signal!(pids, 130)
+        rescue SignalException => e
+          raise unless e.signm == "SIGTERM"
+
+          run_shards_shutdown_on_signal!(pids, 143)
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def run_shards_wait_all_children_sequential(pids, hook_cfg, workers, shard_results, after_hook_err)
+        pids.each do |h|
+          Process.wait(h[:pid])
+          st = $?
+          after_hook_err = run_shards_finalize_reaped_worker!(h, hook_cfg, workers, st, shard_results, after_hook_err)
+        end
+        [shard_results, after_hook_err]
+      end
+
+      # Poll every live PID each tick so wall and idle timeouts apply to all workers, not only the first in wait order.
+      def run_shards_wait_all_children_multiplex(pids, hook_cfg, ctx, workers, timeout_sec, idle_sec, shard_results, after_hook_err)
+        pending = pids.dup
+
+        loop do
+          pending.delete_if do |h|
+            wpid = Process.wait(h[:pid], Process::WNOHANG)
+            next false unless wpid == h[:pid]
+
+            st = $?
+            after_hook_err = run_shards_finalize_reaped_worker!(h, hook_cfg, workers, st, shard_results, after_hook_err)
+            true
+          end
+
+          return [shard_results, after_hook_err] if pending.empty?
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          violation = run_shards_timeout_violation(pids, pending, ctx, now, timeout_sec, idle_sec)
+          if violation
+            reason, timed_h = violation
+            others = pending.reject { |x| x[:pid] == timed_h[:pid] }
+            case reason
+            when :wall_timeout
+              return run_shards_wait_flush_after_worker_timeout!(
+                timed_h, others, hook_cfg, ctx, timeout_sec, workers, shard_results, after_hook_err
+              )
+            when :idle_timeout
+              return run_shards_wait_flush_after_worker_idle!(
+                timed_h, others, hook_cfg, ctx, idle_sec, workers, shard_results, after_hook_err
+              )
+            end
+          end
+
+          sleep(0.2)
+        end
+      end
+
+      # @return [(Symbol, Hash), nil] e.g. +[:wall_timeout, h]+ when a limit is exceeded
+      def run_shards_timeout_violation(pids_order, pending, ctx, now, timeout_sec, idle_sec)
+        pids_order.each do |h|
+          next unless pending.any? { |p| p[:pid] == h[:pid] }
+
+          if timeout_sec && timeout_sec > 0
+            spawned_at = h[:spawned_at] || ctx[:run_t0]
+            return [:wall_timeout, h] if now >= spawned_at + timeout_sec
+          end
+        end
+
+        pids_order.each do |h|
+          next unless pending.any? { |p| p[:pid] == h[:pid] }
+
+          next unless idle_sec && idle_sec > 0 && h[:ping_path]
+
+          t, = run_shards_read_worker_ping_payload(h[:ping_path])
+          return [:idle_timeout, h] if t && (now - t) > idle_sec
+        end
+
+        nil
+      end
+
+      def run_shards_finalize_reaped_worker!(h, hook_cfg, workers, st, shard_results, after_hook_err)
+        exitstatus = st.exitstatus
+        ok = st.success?
+        Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
+        rc = run_shards_invoke_after_shard!(hook_cfg, h[:shard], workers, exitstatus)
+        after_hook_err = rc if rc != 0 && after_hook_err == 0
+        shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
+        run_shards_unlink_ping_path(h[:ping_path])
+        after_hook_err
+      end
+
+      def run_shards_unlink_ping_path(path)
+        s = path.to_s.strip
+        return if s.empty?
+
+        File.unlink(s) if File.file?(s)
+      rescue SystemCallError
+        # best-effort cleanup of tmp/polyrun/worker-ping-*.txt
+      end
+
+      def run_shards_read_worker_ping_time(path)
+        run_shards_read_worker_ping_payload(path)[0]
+      end
+
+      # @return [Array(Float?, String?)] monotonic time and optional location line (path:line)
+      def run_shards_read_worker_ping_payload(path)
+        return [nil, nil] unless path && File.file?(path)
+
+        s = File.binread(path)
+        return [nil, nil] if s.nil? || s.strip.empty?
+
+        time_line, rest = s.split("\n", 2)
+        first = time_line.to_s.strip
+        return [nil, nil] if first.empty?
+
+        f = first.to_f
+        t = f.positive? ? f : nil
+        loc = rest.to_s.strip
+        loc = nil if loc.empty?
+        [t, loc]
+      rescue SystemCallError
+        [nil, nil]
+      end
+
+      def run_shards_wait_flush_after_worker_idle!(timed_h, others, hook_cfg, ctx, idle_sec, workers, shard_results, after_hook_err)
+        run_shards_warn_worker_idle!(timed_h, ctx, idle_sec)
+        run_shards_force_stop_pid_status(timed_h[:pid])
+        run_shards_unlink_ping_path(timed_h[:ping_path])
+        rc = run_shards_invoke_after_shard!(hook_cfg, timed_h[:shard], workers, WORKER_IDLE_TIMEOUT_EXIT_STATUS)
+        after_hook_err = rc if rc != 0 && after_hook_err == 0
+        shard_results << {shard: timed_h[:shard], exitstatus: WORKER_IDLE_TIMEOUT_EXIT_STATUS, success: false}
+        others.each do |h2|
+          st2 = run_shards_wait_or_force_stop_status(h2[:pid])
+          exit2 = st2&.exitstatus
+          ok2 = st2 ? st2.success? : false
+          exit2 = WORKER_IDLE_TIMEOUT_EXIT_STATUS if exit2.nil?
+          run_shards_unlink_ping_path(h2[:ping_path])
+          rc2 = run_shards_invoke_after_shard!(hook_cfg, h2[:shard], workers, exit2)
+          after_hook_err = rc2 if rc2 != 0 && after_hook_err == 0
+          shard_results << {shard: h2[:shard], exitstatus: exit2, success: ok2}
+        end
+        [shard_results, after_hook_err]
+      end
+
+      def run_shards_wait_flush_after_worker_timeout!(timed_h, others, hook_cfg, ctx, timeout_sec, workers, shard_results, after_hook_err)
+        run_shards_warn_worker_timeout!(timed_h, ctx, timeout_sec)
+        run_shards_force_stop_pid_status(timed_h[:pid])
+        run_shards_unlink_ping_path(timed_h[:ping_path])
+        rc = run_shards_invoke_after_shard!(hook_cfg, timed_h[:shard], workers, WORKER_TIMEOUT_EXIT_STATUS)
+        after_hook_err = rc if rc != 0 && after_hook_err == 0
+        shard_results << {shard: timed_h[:shard], exitstatus: WORKER_TIMEOUT_EXIT_STATUS, success: false}
+        others.each do |h2|
+          st2 = run_shards_wait_or_force_stop_status(h2[:pid])
+          exit2 = st2&.exitstatus
+          ok2 = st2 ? st2.success? : false
+          exit2 = WORKER_TIMEOUT_EXIT_STATUS if exit2.nil?
+          run_shards_unlink_ping_path(h2[:ping_path])
+          rc2 = run_shards_invoke_after_shard!(hook_cfg, h2[:shard], workers, exit2)
+          after_hook_err = rc2 if rc2 != 0 && after_hook_err == 0
+          shard_results << {shard: h2[:shard], exitstatus: exit2, success: ok2}
+        end
+        [shard_results, after_hook_err]
+      end
+
+      def run_shards_invoke_after_shard!(hook_cfg, shard, workers, exitstatus)
+        env_after = ENV.to_h.merge(
+          "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+          "POLYRUN_SHARD_INDEX" => shard.to_s,
+          "POLYRUN_SHARD_TOTAL" => workers.to_s,
+          "POLYRUN_WORKER_EXIT_STATUS" => exitstatus.to_s
+        )
+        hook_cfg.run_phase_if_enabled(:after_shard, env_after)
+      end
+
+      def run_shards_warn_worker_idle!(h, ctx, idle_sec)
+        paths = ctx[:plan].shard(h[:shard])
+        sample = paths.first(5).join(", ")
+        suffix =
+          if paths.empty?
+            " (no paths)"
+          elsif paths.size > 5
+            " (#{paths.size} files total)"
+          else
+            ""
+          end
+        _t, loc = run_shards_read_worker_ping_payload(h[:ping_path])
+        ping_suffix = (loc && !loc.to_s.strip.empty?) ? "; last ping #{loc.to_s.strip}" : ""
+        Polyrun::Log.orchestration_warn "polyrun run-shards: WORKER IDLE TIMEOUT after #{idle_sec}s since last per-example progress ping — shard #{h[:shard]} pid #{h[:pid]}#{ping_suffix}."
+        Polyrun::Log.warn "polyrun run-shards: idle shard file sample: #{sample}#{suffix}"
+        Polyrun::Log.warn "polyrun run-shards: use Polyrun::RSpec.install_worker_ping! / Polyrun::Minitest.install_worker_ping! (Polyrun Quick calls ping! each example); exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
+      end
+
+      def run_shards_wait_or_force_stop_status(pid)
+        wpid = Process.wait(pid, Process::WNOHANG)
+        return $? if wpid == pid
+
+        run_shards_force_stop_pid_status(pid)
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def run_shards_force_stop_pid_status(pid)
+        Process.kill(:KILL, pid)
+        st = nil
+        begin
+          Process.wait(pid)
+          st = $?
+        rescue Errno::ECHILD
+          # child already reaped
+        end
+        st
+      rescue Errno::ESRCH
+        begin
+          Process.wait(pid)
+          $?
+        rescue Errno::ECHILD
+          nil
+        end
+      end
+
+      def run_shards_warn_worker_timeout!(h, ctx, timeout_sec)
+        paths = ctx[:plan].shard(h[:shard])
+        sample = paths.first(5).join(", ")
+        suffix =
+          if paths.empty?
+            " (no paths)"
+          elsif paths.size > 5
+            " (#{paths.size} files total)"
+          else
+            ""
+          end
+        Polyrun::Log.orchestration_warn "polyrun run-shards: WORKER TIMEOUT after #{timeout_sec}s (wall time since worker spawn) — shard #{h[:shard]} pid #{h[:pid]}."
+        Polyrun::Log.warn "polyrun run-shards: timeout shard includes: #{sample}#{suffix}"
+        Polyrun::Log.warn "polyrun run-shards: override with --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC; recorded exit #{WORKER_TIMEOUT_EXIT_STATUS} for this worker."
+      end
+    end
+  end
+end
+# rubocop:enable Polyrun/FileLength, Metrics/ModuleLength

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Polyrun/FileLength -- run-shards boot phases A/B
 require "shellwords"
 
 module Polyrun
@@ -19,22 +20,43 @@ module Polyrun
         err = run_shards_validate_cmd(cmd)
         return [:fail, err] if err
 
+        run_shards_normalize_worker_timeout_option!(o)
+        run_shards_normalize_worker_idle_timeout_option!(o)
+
         cmd = Shellwords.split(cmd.first) if cmd.size == 1 && cmd.first.include?(" ")
 
         [:ok, o, cmd]
       end
 
+      # rubocop:disable Metrics/AbcSize -- items + costs + plan emit for run-shards
       def run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
         items, paths_source, err = run_shards_resolve_items(o[:paths_file], pc)
         return [err, nil] if err
 
-        costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])
+        costs, strategy, err = run_shards_resolve_costs(
+          o[:timing_path],
+          o[:strategy],
+          o[:timing_granularity],
+          strategy_explicit: o[:strategy_explicit]
+        )
         return [err, nil] if err
 
         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])
+        stable = load_stable_assignment(pc)
+        plan = run_shards_make_plan(
+          items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity], stable,
+          shard_weights: pc["shard_weights"] || pc[:shard_weights]
+        )
+
+        partition_emit_diagnostics!(
+          plan: plan,
+          items: items,
+          costs: costs,
+          timing_path: o[:timing_path],
+          granularity: o[:timing_granularity]
+        )
 
         run_shards_debug_shard_sizes(plan, o[:workers])
         Polyrun::Log.warn "polyrun run-shards: #{items.size} paths → #{o[:workers]} workers (#{strategy})" if @verbose
@@ -44,6 +66,7 @@ module Polyrun
 
         [nil, run_shards_plan_context_hash(o, cmd, cfg, plan, run_t0, parallel, config_path)]
       end
+      # rubocop:enable Metrics/AbcSize
 
       def run_shards_plan_boot(argv, config_path)
         run_t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -66,6 +89,7 @@ module Polyrun
           strategy: strategy,
           merge_coverage: o[:merge_coverage],
           merge_failures: run_shards_merge_failures_flag(o, cfg),
+          merge_spec_quality: run_shards_merge_spec_quality_flag(o, cfg),
           command: cmd,
           timing_path: o[:timing_path],
           paths_source: paths_source,
@@ -73,6 +97,26 @@ module Polyrun
         )
       end
 
+      def run_shards_merge_spec_quality_flag(o, cfg)
+        return true if o[:merge_spec_quality]
+        return true if %w[1 true yes].include?(ENV["POLYRUN_MERGE_SPEC_QUALITY"].to_s.downcase)
+
+        rep = cfg.reporting
+        v = rep["merge_spec_quality"] || rep[:merge_spec_quality]
+        v == true || %w[1 true yes].include?(v.to_s.downcase)
+      end
+
+      def run_shards_merge_spec_quality_output_opt(o, cfg)
+        x = o[:merge_spec_quality_output]
+        return x if x && !x.to_s.strip.empty?
+
+        x = ENV["POLYRUN_MERGED_SPEC_QUALITY_OUT"]
+        return x if x && !x.to_s.strip.empty?
+
+        rep = cfg.reporting
+        rep["merge_spec_quality_output"] || rep[:merge_spec_quality_output]
+      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)
@@ -118,9 +162,43 @@ module Polyrun
           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
+          merge_spec_quality: run_shards_merge_spec_quality_flag(o, cfg),
+          merge_spec_quality_output: run_shards_merge_spec_quality_output_opt(o, cfg),
+          report_spec_quality: o[:report_spec_quality] != false,
+          config_path: config_path,
+          worker_timeout_sec: run_shards_resolved_worker_timeout_sec(o),
+          worker_idle_timeout_sec: run_shards_resolved_worker_idle_timeout_sec(o)
         }
       end
+
+      def run_shards_normalize_worker_idle_timeout_option!(o)
+        v = o[:worker_idle_timeout_sec]
+        return if v.nil?
+
+        o[:worker_idle_timeout_sec] = nil if v <= 0
+      end
+
+      def run_shards_resolved_worker_idle_timeout_sec(o)
+        cli = o[:worker_idle_timeout_sec]
+        return cli.to_f if cli.is_a?(Numeric) && cli > 0
+
+        env_worker_idle_timeout_sec
+      end
+
+      def run_shards_normalize_worker_timeout_option!(o)
+        v = o[:worker_timeout_sec]
+        return if v.nil?
+
+        o[:worker_timeout_sec] = nil if v <= 0
+      end
+
+      def run_shards_resolved_worker_timeout_sec(o)
+        cli = o[:worker_timeout_sec]
+        return cli.to_f if cli.is_a?(Numeric) && cli > 0
+
+        env_worker_timeout_sec
+      end
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -18,6 +18,7 @@ module Polyrun
           workers: env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS),
           paths_file: nil,
           strategy: (pc["strategy"] || pc[:strategy] || "round_robin").to_s,
+          strategy_explicit: !!(pc["strategy"] || pc[:strategy]),
           seed: pc["seed"] || pc[:seed],
           timing_path: nil,
           constraints_path: nil,
@@ -27,7 +28,12 @@ module Polyrun
           merge_format: nil,
           merge_failures: false,
           merge_failures_output: nil,
-          merge_failures_format: nil
+          merge_failures_format: nil,
+          merge_spec_quality: false,
+          merge_spec_quality_output: nil,
+          report_spec_quality: true,
+          worker_timeout_sec: nil,
+          worker_idle_timeout_sec: nil
         }
       end
 
@@ -39,9 +45,14 @@ module Polyrun
 
       # 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] [--merge-failures] [--merge-failures-output P] [--merge-failures-format jsonl|json] [--] <command> [args...]"
+        opts.banner = "usage: polyrun run-shards [--workers N] [--worker-timeout SEC] [--worker-idle-timeout SEC] [--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] [--merge-spec-quality] [--merge-spec-quality-output P] [--no-report-spec-quality] [--] <command> [args...]"
         opts.on("--workers N", Integer) { |v| st[:workers] = v }
-        opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
+        opts.on("--worker-timeout SEC", Float, "Max seconds per worker since spawn (also POLYRUN_WORKER_TIMEOUT_SEC); kills stuck workers (exit 124)") { |v| st[:worker_timeout_sec] = v }
+        opts.on("--worker-idle-timeout SEC", Float, "Max seconds since last valid WorkerPing timestamp in POLYRUN_WORKER_PING_FILE (needs prior ping); RSpec/Minitest: install_worker_ping!; Quick: automatic; exit 125") { |v| st[:worker_idle_timeout_sec] = v }
+        opts.on("--strategy NAME", String) do |v|
+          st[:strategy] = v
+          st[:strategy_explicit] = true
+        end
         opts.on("--seed VAL") { |v| st[:seed] = v }
         opts.on("--paths-file PATH", String) { |v| st[:paths_file] = v }
         opts.on("--constraints PATH", String) { |v| st[:constraints_path] = v }
@@ -53,6 +64,9 @@ module Polyrun
         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 }
+        opts.on("--merge-spec-quality", "After workers exit, merge coverage/polyrun-spec-quality-fragment-*.jsonl (POLYRUN_SPEC_QUALITY in workers)") { st[:merge_spec_quality] = true }
+        opts.on("--merge-spec-quality-output PATH", String) { |v| st[:merge_spec_quality_output] = v }
+        opts.on("--no-report-spec-quality", "Skip printing spec-quality report after merge") { st[:report_spec_quality] = false }
       end
       # rubocop:enable Metrics/AbcSize
     end

data/lib/polyrun/cli/run_shards_planning.rb

@@ -23,13 +23,10 @@ module Polyrun
         run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
       end
 
-      def run_shards_default_timing_path(pc, timing_path, strategy)
+      def run_shards_default_timing_path(pc, timing_path, _strategy = nil)
         return timing_path if timing_path
 
-        tf = pc["timing_file"] || pc[:timing_file]
-        return tf if tf && (Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy))
-
-        nil
+        pc["timing_file"] || pc[:timing_file]
       end
 
       def run_shards_validate_workers!(o)
@@ -70,8 +67,13 @@ module Polyrun
         [items, paths_source, nil]
       end
 
-      def run_shards_resolve_costs(timing_path, strategy, timing_granularity)
+      def run_shards_resolve_costs(timing_path, strategy, timing_granularity, strategy_explicit: false)
+        strategy = strategy.to_s
         if timing_path
+          if strategy_explicit && strategy == "round_robin"
+            return [nil, strategy, nil]
+          end
+
           costs = Polyrun::Partition::Plan.load_timing_costs(
             File.expand_path(timing_path.to_s, Dir.pwd),
             granularity: timing_granularity
@@ -80,12 +82,16 @@ module Polyrun
             Polyrun::Log.warn "polyrun run-shards: timing file missing or empty: #{timing_path}"
             return [nil, nil, 2]
           end
-          unless Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy)
+          if Polyrun::Partition::Plan.timing_load_strategy?(strategy)
+            return [costs, strategy, nil]
+          end
+          unless strategy_explicit
             Polyrun::Log.warn "polyrun run-shards: using cost_binpack (timing data present)" if @verbose
-            strategy = "cost_binpack"
+            return [costs, "cost_binpack", nil]
           end
-          [costs, strategy, nil]
-        elsif Polyrun::Partition::Plan.cost_strategy?(strategy)
+
+          [nil, strategy, nil]
+        elsif Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.lazy_robin_strategy?(strategy)
           Polyrun::Log.warn "polyrun run-shards: --timing or partition.timing_file required for strategy #{strategy}"
           [nil, nil, 2]
         else
@@ -93,7 +99,7 @@ module Polyrun
         end
       end
 
-      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity)
+      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity, stable_assignment = nil, shard_weights: nil)
         Polyrun::Debug.time("Partition::Plan.new (partition #{items.size} paths → #{workers} shards)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -103,7 +109,9 @@ module Polyrun
             costs: costs,
             constraints: constraints,
             root: Dir.pwd,
-            timing_granularity: timing_granularity
+            timing_granularity: timing_granularity,
+            stable_assignment: stable_assignment,
+            shard_weights: shard_weights
           )
         end
       end