polyrun 1.4.2 → 2.1.0

data/lib/polyrun/cli/run_shards_run.rb

@@ -1,7 +1,9 @@
 require "shellwords"
 require "rbconfig"
+require "json"
 
 require_relative "run_shards_planning"
+require_relative "run_shards_worker_interrupt"
 require_relative "run_shards_parallel_children"
 
 module Polyrun
@@ -9,6 +11,7 @@ module Polyrun
     # Partition + spawn workers for `polyrun run-shards` (keeps {RunShardsCommand} file small).
     module RunShardsRun
       include RunShardsPlanning
+      include RunShardsWorkerInterrupt
       include RunShardsParallelChildren
 
       private
@@ -20,13 +23,15 @@ module Polyrun
         run_shards_workers_and_merge(ctx)
       end
 
-      # rubocop:disable Metrics/AbcSize -- orchestration: hooks, merge, worker failures
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- orchestration: hooks, merge, worker failures
       def run_shards_workers_and_merge(ctx)
         hook_cfg = Polyrun::Hooks.from_config(ctx[:cfg])
         suite_started = false
         exit_code = 1
         merged_failures_path = nil
         merge_failures_errored = false
+        merge_spec_quality_errored = false
+        spec_quality_strict_failed = false
 
         begin
           env_suite = ENV.to_h.merge(
@@ -62,6 +67,20 @@ module Polyrun
             Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
           end
 
+          if ctx[:merge_spec_quality]
+            begin
+              merged_sq_path = merge_spec_quality_after_shards(ctx)
+              if merged_sq_path && ctx[:report_spec_quality]
+                cfg = load_spec_quality_config(nil)
+                merged = JSON.parse(File.read(merged_sq_path))
+                spec_quality_strict_failed = cfg["strict"] && Polyrun::SpecQuality::Report.gate_violations(merged, cfg).any?
+              end
+            rescue Polyrun::Error, JSON::ParserError => e
+              Polyrun::Log.warn e.message.to_s
+              merge_spec_quality_errored = true
+            end
+          end
+
           if ctx[:merge_failures]
             begin
               merged_failures_path = merge_failures_after_shards(ctx)
@@ -77,13 +96,13 @@ module Polyrun
               merge_failures: ctx[:merge_failures]
             )
             exit_code = 1
-            exit_code = 1 if wait_hook_err != 0
             return exit_code
           end
 
           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 = 1 if merge_spec_quality_errored && exit_code == 0
+          exit_code = 1 if spec_quality_strict_failed && exit_code == 0
           exit_code
         ensure
           if suite_started
@@ -93,11 +112,15 @@ module Polyrun
               "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)
+            begin
+              hook_cfg.run_phase_if_enabled(:after_suite, env_after)
+            rescue Interrupt
+              Polyrun::Log.warn "polyrun run-shards: after_suite hook interrupted; workers are stopped or were not started"
+            end
           end
         end
       end
-      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
@@ -106,38 +129,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
 
-      # Best-effort worker teardown then exit. Does not return.
-      def run_shards_shutdown_on_signal!(pids, code)
-        run_shards_terminate_children!(pids)
-        exit(code)
-      rescue Interrupt
-        pids.each do |h|
-          Process.kill(:KILL, h[:pid])
-        rescue Errno::ESRCH
-          # already reaped
-        end
-        pids.each do |h|
-          Process.wait(h[:pid])
-        rescue Errno::ESRCH, Errno::ECHILD, Interrupt
-          # already reaped or give up
-        end
-        exit(code)
-      end
-
-      # Send SIGTERM to each worker PID and wait so Ctrl+C / SIGTERM does not leave orphans.
-      def run_shards_terminate_children!(pids)
-        pids.each do |h|
-          Process.kill(:TERM, h[:pid])
-        rescue Errno::ESRCH
-          # already reaped
-        end
-        pids.each do |h|
-          Process.wait(h[:pid])
-        rescue Errno::ESRCH, Errno::ECHILD
-          # already reaped
-        end
-      end
-
       def run_shards_merge_or_hint_coverage(ctx)
         if ctx[:merge_coverage]
           mo = ctx[:merge_output] || "coverage/merged.json"

data/lib/polyrun/cli/run_shards_worker_interrupt.rb

@@ -0,0 +1,75 @@
+module Polyrun
+  class CLI
+    # SIGINT/SIGTERM handling and non-blocking reap for parallel worker PIDs (used by run-shards / ci-shard fan-out).
+    module RunShardsWorkerInterrupt
+      private
+
+      def run_shards_log_interrupt_workers(pids, _ctx)
+        parts = pids.map { |h| "shard=#{h[:shard]} pid=#{h[:pid]}" }
+        Polyrun::Log.orchestration_warn "polyrun run-shards: SIGINT/SIGTERM while waiting on workers — stopping: #{parts.join(", ")}"
+        Polyrun::Log.warn "polyrun run-shards: search this log for each shard's started … pid= line and RSpec output; repeat SIGINT during cleanup escalates to SIGKILL"
+      end
+
+      # Best-effort worker teardown then exit. Does not return.
+      def run_shards_shutdown_on_signal!(pids, code)
+        run_shards_log_interrupt_workers(pids, nil)
+        run_shards_terminate_children!(pids)
+        exit(code)
+      rescue Interrupt
+        run_shards_signal_workers_kill(pids)
+        run_shards_reap_worker_pids_interruptible(pids.map { |h| h[:pid] })
+        exit(code)
+      end
+
+      # Send SIGTERM to each worker PID and wait so Ctrl+C / SIGTERM does not leave orphans.
+      def run_shards_terminate_children!(pids)
+        run_shards_signal_workers_term(pids)
+        run_shards_reap_worker_pids_interruptible(pids.map { |h| h[:pid] })
+      end
+
+      def run_shards_signal_workers_term(pids)
+        pids.each do |h|
+          Process.kill(:TERM, h[:pid])
+        rescue Errno::ESRCH
+        end
+      end
+
+      def run_shards_signal_workers_kill(pids)
+        pids.each do |h|
+          Process.kill(:KILL, h[:pid])
+        rescue Errno::ESRCH
+        end
+      end
+
+      # Reap child PIDs without blocking uninterruptibly on one stuck zombie (avoids noisy stacks on repeat Ctrl+C).
+      def run_shards_reap_worker_pids_interruptible(pids)
+        pending = pids.compact.uniq
+        force_note = false
+        until pending.empty?
+          pending.reject! do |pid|
+            w = Process.wait(pid, Process::WNOHANG)
+            next true if w == pid
+
+            false
+          rescue Errno::ECHILD
+            true
+          end
+          break if pending.empty?
+
+          begin
+            sleep(0.05)
+          rescue Interrupt
+            unless force_note
+              force_note = true
+              Polyrun::Log.orchestration_warn "polyrun run-shards: repeated SIGINT during worker cleanup — SIGKILL to #{pending.size} process(es)"
+            end
+            pending.each do |pid|
+              Process.kill(:KILL, pid)
+            rescue Errno::ESRCH
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/cli/spec_quality_commands.rb

@@ -0,0 +1,140 @@
+require "json"
+require "optparse"
+
+require_relative "../spec_quality"
+
+module Polyrun
+  class CLI
+    module SpecQualityCommands
+      private
+
+      def cmd_merge_spec_quality(argv)
+        inputs = []
+        output = "coverage/polyrun-spec-quality.json"
+        parser = OptionParser.new do |opts|
+          opts.banner = "usage: polyrun merge-spec-quality [-i FILE]... [-o OUT] [FILE...]"
+          opts.on("-i", "--input FILE", "Spec quality JSONL fragment (repeatable)") { |f| inputs << f }
+          opts.on("-o", "--output PATH", String) { |v| output = v }
+        end
+        parser.parse!(argv)
+        inputs.concat(argv) if inputs.empty?
+
+        if inputs.empty?
+          inputs = Dir.glob(Polyrun::SpecQuality::Fragment.glob_pattern).sort
+        end
+
+        if inputs.empty?
+          Polyrun::Log.warn "merge-spec-quality: need -i FILE or coverage/polyrun-spec-quality-fragment-*.jsonl"
+          return 2
+        end
+
+        out_abs = File.expand_path(output)
+        Polyrun::SpecQuality::Merge.merge_and_write(inputs.map { |p| File.expand_path(p) }, out_abs)
+        Polyrun::Log.puts out_abs
+        0
+      end
+
+      # rubocop:disable Metrics/AbcSize -- report argv + gate output
+      def cmd_report_spec_quality(argv)
+        input = nil
+        out_file = nil
+        top = 30
+        profile = nil
+        config_path = nil
+        strict = false
+        json_out = false
+        plan_paths = []
+
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun report-spec-quality -i FILE [-o PATH] [--top N] [--profile LIST] [--strict] [--json]"
+          opts.on("-i", "--input PATH", "Merged polyrun-spec-quality.json") { |v| input = v }
+          opts.on("-o", "--output PATH", "Write report to file instead of stdout") { |v| out_file = v }
+          opts.on("--top N", Integer) { |v| top = v }
+          opts.on("--profile LIST", "cpu,mem,io,wall (comma-separated)") { |v| profile = v }
+          opts.on("-c", "--config PATH", "polyrun_spec_quality.yml path") { |v| config_path = v }
+          opts.on("--plan PATH", "Partition plan JSON (repeatable; polyrun plan output per shard)") { |v| plan_paths << v }
+          opts.on("--strict", "Exit 1 when gate thresholds fail") { strict = true }
+          opts.on("--json", "Write analysis JSON instead of text report") { json_out = true }
+        end.parse!(argv)
+        input ||= argv.first
+
+        unless input && File.file?(input)
+          Polyrun::Log.warn "report-spec-quality: need -i FILE"
+          return 2
+        end
+
+        merged = JSON.parse(File.read(File.expand_path(input)))
+        cfg = load_spec_quality_config(config_path)
+        strict = true if cfg["strict"] || strict
+        plan_shards = Polyrun::SpecQuality::PlanLoader.load_shards(plan_paths)
+
+        text = if json_out
+          JSON.pretty_generate(Polyrun::SpecQuality::Report.analyze(merged, cfg, plan_shards: plan_shards))
+        else
+          Polyrun::SpecQuality::Report.format_report(
+            merged, cfg: cfg, top: top, profile: profile, plan_shards: plan_shards
+          )
+        end
+
+        if out_file
+          File.write(File.expand_path(out_file), text)
+          Polyrun::Log.puts File.expand_path(out_file)
+        else
+          Polyrun::Log.print text
+        end
+
+        violations = Polyrun::SpecQuality::Report.gate_violations(merged, cfg)
+        if strict && violations.any?
+          violations.each { |v| Polyrun::Log.warn "polyrun spec-quality gate: #{v}" }
+          return 1
+        end
+
+        0
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def merge_spec_quality_after_shards(ctx)
+        files = merge_spec_quality_fragment_files
+        if files.empty?
+          Polyrun::Log.warn "polyrun run-shards: --merge-spec-quality: no coverage/polyrun-spec-quality-fragment-*.jsonl found (enable POLYRUN_SPEC_QUALITY in spec_helper?)"
+          return nil
+        end
+
+        out = ctx[:merge_spec_quality_output] || "coverage/polyrun-spec-quality.json"
+        Polyrun::Log.warn "polyrun run-shards: merging #{files.size} spec-quality fragment(s) → #{out}"
+        Polyrun::SpecQuality::Merge.merge_and_write(files, File.expand_path(out))
+        report_spec_quality_after_merge(out, ctx)
+        File.expand_path(out)
+      end
+
+      def report_spec_quality_after_merge(merged_path, ctx)
+        return unless ctx[:report_spec_quality]
+
+        cfg = load_spec_quality_config(ctx[:config_path])
+        merged = JSON.parse(File.read(File.expand_path(merged_path)))
+        text = Polyrun::SpecQuality::Report.format_report(merged, cfg: cfg)
+        Polyrun::Log.print text
+
+        violations = Polyrun::SpecQuality::Report.gate_violations(merged, cfg)
+        return if violations.empty?
+
+        violations.each { |v| Polyrun::Log.warn "polyrun spec-quality gate: #{v}" }
+      end
+
+      def merge_spec_quality_fragment_files
+        Dir.glob(Polyrun::SpecQuality::Fragment.glob_pattern).sort
+      end
+
+      def load_spec_quality_config(config_path)
+        root = Dir.pwd
+        path = config_path
+        if path && !path.to_s.empty?
+          path = File.expand_path(path, root)
+        end
+        Polyrun::SpecQuality::Config.load(root: root, config_path: path)
+      rescue
+        Polyrun::SpecQuality::Config::DEFAULTS.dup
+      end
+    end
+  end
+end

data/lib/polyrun/cli.rb

@@ -1,6 +1,8 @@
+# rubocop:disable Polyrun/FileLength -- CLI dispatch + require wiring
 require "optparse"
 
 require_relative "cli/helpers"
+require_relative "cli/partition_diagnostics"
 require_relative "cli/plan_command"
 require_relative "cli/prepare_command"
 require_relative "cli/coverage_commands"
@@ -8,8 +10,10 @@ require_relative "cli/report_commands"
 require_relative "cli/env_commands"
 require_relative "cli/database_commands"
 require_relative "cli/run_shards_command"
+require_relative "cli/run_queue_command"
 require_relative "cli/queue_command"
 require_relative "cli/timing_command"
+require_relative "cli/spec_quality_commands"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
 require_relative "cli/ci_shard_run_parse"
@@ -28,9 +32,9 @@ 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 merge-failures report-coverage report-junit report-timing
+      plan prepare merge-coverage merge-failures merge-spec-quality report-coverage report-junit report-timing report-spec-quality
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
-      run-shards parallel-rspec start build-paths init queue quick hook
+      run-shards parallel-rspec start build-paths init queue run-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.
@@ -39,6 +43,7 @@ module Polyrun
     ).freeze
 
     include Helpers
+    include PartitionDiagnostics
     include PlanCommand
     include PrepareCommand
     include CoverageCommands
@@ -46,8 +51,10 @@ module Polyrun
     include EnvCommands
     include DatabaseCommands
     include RunShardsCommand
+    include RunQueueCommand
     include QueueCommand
     include TimingCommand
+    include SpecQualityCommands
     include InitCommand
     include QuickCommand
     include CiShardRunParse
@@ -159,6 +166,10 @@ module Polyrun
         cmd_config(argv, config_path)
       when "merge-timing"
         cmd_merge_timing(argv)
+      when "merge-spec-quality"
+        cmd_merge_spec_quality(argv)
+      when "report-spec-quality"
+        cmd_report_spec_quality(argv)
       when "db:setup-template"
         cmd_db_setup_template(argv, config_path)
       when "db:setup-shard"
@@ -179,6 +190,8 @@ module Polyrun
         cmd_init(argv, config_path)
       when "queue"
         cmd_queue(argv)
+      when "run-queue"
+        cmd_run_queue(argv, config_path)
       when "quick"
         cmd_quick(argv)
       when "hook"
@@ -196,3 +209,4 @@ module Polyrun
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/coverage/example_diff.rb

@@ -0,0 +1,122 @@
+module Polyrun
+  module Coverage
+    # Per-example line hit deltas from stdlib +Coverage.peek_result+ snapshots.
+    module ExampleDiff
+      module_function
+
+      # @return [Hash{String=>Hash}] path => +{"lines"=>[...]}+
+      def peek_blob
+        return {} unless coverage_active?
+
+        normalize_peek(::Coverage.peek_result)
+      end
+
+      def coverage_active?
+        defined?(::Coverage) && ::Coverage.respond_to?(:running?) && ::Coverage.running?
+      end
+
+      def normalize_peek(raw)
+        out = {}
+        raw.each do |path, cov|
+          next unless cov.is_a?(Hash)
+
+          lines = cov[:lines] || cov["lines"]
+          next unless lines.is_a?(Array)
+
+          out[path.to_s] = {"lines" => lines.map { |x| x }}
+        end
+        out
+      end
+
+      # @return [Hash] +:unique_lines+, +:line_churn+, +:max_line_churn+, +:lines+ (compact triples)
+      # rubocop:disable Metrics/AbcSize -- per-file coverage delta walk
+      def diff(before_blob, after_blob)
+        before_blob ||= {}
+        after_blob ||= {}
+        files = before_blob.keys | after_blob.keys
+
+        line_entries = []
+        unique = 0
+        churn = 0
+        max_churn = 0
+
+        files.each do |path|
+          b_lines = line_array(before_blob[path])
+          a_lines = line_array(after_blob[path])
+          max_len = [b_lines.size, a_lines.size].max
+
+          (0...max_len).each do |i|
+            b = b_lines[i]
+            a = a_lines[i]
+            next if a.nil? && b.nil?
+
+            delta = (integer_hit(a) - integer_hit(b))
+            next unless delta.positive?
+
+            line_no = i + 1
+            line_entries << [path, line_no, delta]
+            unique += 1
+            churn += delta
+            max_churn = delta if delta > max_churn
+          end
+        end
+
+        {
+          unique_lines: unique,
+          line_churn: churn,
+          max_line_churn: max_churn,
+          lines: line_entries
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def filter_lines(lines, root:, track_under:, ignore_paths: [])
+        root = File.expand_path(root)
+        prefixes = Array(track_under).map { |d| File.join(root, d.to_s) }
+        ignore = Array(ignore_paths).map(&:to_s).reject(&:empty?)
+
+        lines.select do |path, _line, _delta|
+          p = File.expand_path(path.to_s, root)
+          next false if ignore.any? { |pat| path_matches_ignore?(p, pat) }
+
+          prefixes.any? { |pre| p == pre || p.start_with?(pre + "/") }
+        end
+      end
+
+      def apply_track_under(delta, root:, track_under:, ignore_paths: [])
+        filtered = filter_lines(delta[:lines] || [], root: root, track_under: track_under, ignore_paths: ignore_paths)
+        unique = filtered.size
+        churn = filtered.sum { |(_p, _l, d)| d }
+        max_churn = filtered.map { |(_p, _l, d)| d }.max || 0
+        {
+          unique_lines: unique,
+          line_churn: churn,
+          max_line_churn: max_churn,
+          lines: filtered
+        }
+      end
+
+      def path_matches_ignore?(path, pattern)
+        return path.include?(pattern) if pattern.is_a?(String) && !pattern.start_with?("/")
+
+        path.match?(Regexp.new(pattern))
+      rescue RegexpError
+        path.include?(pattern.to_s)
+      end
+
+      def line_array(entry)
+        return [] unless entry.is_a?(Hash)
+
+        arr = entry["lines"] || entry[:lines]
+        arr.is_a?(Array) ? arr : []
+      end
+
+      def integer_hit(value)
+        return 0 if value.nil?
+
+        value.is_a?(Integer) ? value : value.to_i
+      end
+      private_class_method :line_array, :integer_hit
+    end
+  end
+end

data/lib/polyrun/coverage/merge/formatters_html.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Polyrun/FileLength -- HTML merge formatter + helpers in one file
 require "cgi"
 require "digest/sha1"
 require "erb"
@@ -9,6 +10,7 @@ module Polyrun
       module_function
 
       # Standalone HTML report with summary, file table, and per-file source details.
+      # rubocop:disable Metrics/AbcSize -- linear assembly of overview, file table, sections, asset reads
       def emit_html(coverage_blob, title: "Polyrun coverage", root: nil, groups: nil, generated_at: Time.now)
         files = coverage_blob.keys.sort.map { |path| html_file_payload(path, coverage_blob[path], root) }
         summary = html_summary(files)
@@ -31,6 +33,7 @@ module Polyrun
           javascript: File.read(html_javascript_path)
         )
       end
+      # rubocop:enable Metrics/AbcSize
 
       def html_asset_dir
         File.join(__dir__, "html")
@@ -197,3 +200,4 @@ module Polyrun
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/data/factory_counts.rb

@@ -6,11 +6,19 @@ module Polyrun
       class << self
         def reset!
           @counts = Hash.new(0)
+          @example_counts = Hash.new(0)
+        end
+
+        def reset_example!
+          @example_counts = Hash.new(0)
         end
 
         def record(factory_name)
           @counts ||= Hash.new(0)
-          @counts[factory_name.to_s] += 1
+          @example_counts ||= Hash.new(0)
+          name = factory_name.to_s
+          @counts[name] += 1
+          @example_counts[name] += 1
         end
 
         def counts
@@ -18,6 +26,11 @@ module Polyrun
           @counts.dup
         end
 
+        def example_counts
+          @example_counts ||= Hash.new(0)
+          @example_counts.dup
+        end
+
         def summary_lines(top: 20)
           @counts ||= Hash.new(0)
           sorted = @counts.sort_by { |_, n| -n }

data/lib/polyrun/database/clone_shards.rb

@@ -57,6 +57,8 @@ module Polyrun
             end
 
             plan.each { |row| create_one_shard!(row, replace, force_drop, dry_run) }
+          rescue => e
+            raise Polyrun::Error, "CloneShards shard_index=#{shard_index}: #{e.message}"
           end
         end
         threads.each(&:join)

data/lib/polyrun/database/shard.rb

@@ -44,11 +44,12 @@ module Polyrun
 
         return u unless u.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
 
-        if (m = u.match(%r{/([^/?]+)(\?|$)}))
+        if (m = u.match(%r{\A[a-z][a-z0-9+.-]*://[^/?#]+/([^/?]+)(\?|$)}i))
           base = m[1]
           suffixed = "#{base}_#{Integer(shard_index)}"
           u.sub(%r{/#{Regexp.escape(base)}(\?|$)}, "/#{suffixed}\\1")
         else
+          Polyrun::Log.warn "polyrun database: URL has no database segment; shard suffix skipped: #{u}"
           u
         end
       end

data/lib/polyrun/hooks.rb

@@ -118,6 +118,9 @@ module Polyrun
       if reg&.any?(phase)
         begin
           reg.run(phase, merged)
+        rescue Interrupt
+          Polyrun::Log.warn "polyrun hooks: #{phase} ruby hook interrupted"
+          return 130
         rescue => e
           Polyrun::Log.warn "polyrun hooks: #{phase} ruby hook failed: #{e.class}: #{e.message}"
           return 1
@@ -125,7 +128,12 @@ module Polyrun
       end
 
       commands_for(phase).each do |cmd|
-        ok = system(merged, "sh", "-c", cmd)
+        ok = begin
+          system(merged, "sh", "-c", cmd)
+        rescue Interrupt
+          Polyrun::Log.warn "polyrun hooks: #{phase} shell hook interrupted"
+          return 130
+        end
         return $?.exitstatus unless ok
       end
       0

data/lib/polyrun/log.rb

@@ -6,6 +6,9 @@ module Polyrun
   #
   #   Polyrun::Log.stderr = Logger.new($stderr)
   #   Polyrun::Log.stdout = StringIO.new
+  #
+  # Orchestration (+orchestration_warn+): worker timeout and SIGINT lines use the same sink as +warn+ unless
+  # +POLYRUN_ORCHESTRATION_STDERR=1+ and stderr is not process +$stderr+ (then the summary is copied to +$stderr+).
   module Log
     class << self
       attr_writer :stderr
@@ -25,6 +28,19 @@ module Polyrun
         emit_line(stderr, msg)
       end
 
+      # Like {#warn}, and when +POLYRUN_ORCHESTRATION_STDERR=1+ and {#stderr} is not the process +$stderr+,
+      # also writes one line to +$stderr+ so timeout/interrupt attribution survives custom/null Log sinks.
+      def orchestration_warn(msg)
+        warn(msg)
+        return unless %w[1 true yes].include?(ENV["POLYRUN_ORCHESTRATION_STDERR"]&.downcase)
+        return if stderr.equal?($stderr)
+
+        # Intentionally the real stderr stream (+Kernel#warn+ routes through +Log.stderr+).
+        # rubocop:disable Style/StderrPuts
+        $stderr.puts(msg.to_s.chomp)
+        # rubocop:enable Style/StderrPuts
+      end
+
       def puts(msg = "")
         if msg.nil?
           stdout.write("\n")