polyrun 2.1.2 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 756cf8e1b8e2176c4097520752dfdd4b856d03b134a999462641f90a9f217e71
-  data.tar.gz: 284e536d886b4bfc913415b0e3301a31ca98ef3446da1b24163bcc6af485e642
+  metadata.gz: 4a5cd4e5af5195cb25ca3185b3e828556746f21a6911f8a60f1b43b5b6a316d0
+  data.tar.gz: 67362c68f463339cfd8a66e665b9fb6a5f75cf8ed6276e1a846c68147a27e848
 SHA512:
-  metadata.gz: 445f64e0e62be50ab6c63026f27ad8f5f093521bbeed4a05b0ce7adc6a13bcb0496f1489d8243b403f859826e599194c3399a761a9210cbbf5d8027f3fdba52e
-  data.tar.gz: 554a292c2c7ac40e3df11d886ca7a71c10b81f1fa144af00c5c1d20b950ff6d999306be1e3fa75a9982450b2d202bc2bee34d5201ab39dbb386b1b73b42f1403
+  metadata.gz: b7f7ff8592774bfb1bd173753f5c3cca77d99a392a9dbabdd0bf11c85b510a3dc4cf0c2a66912cf5d48384445e74039a2cfa296d6aeb40b5d008aa575700ef0b
+  data.tar.gz: 05aad7cb17b505112548d072895d56c88f885f07b31e3052ab12e5b4ab0979a555bdf9872380107a60211a8bd54dbd176b98a8970eaba7756fa2e87f8a475a15

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 2.1.3 (2026-07-10)
+
+- Add `Polyrun::WorkerOutput` for per-shard worker stdout/stderr routing (`POLYRUN_WORKER_OUTPUT_ROUTING=1` or `POLYRUN_WORKER_LOG_DIR`); optional prefixed TTY echo (`POLYRUN_WORKER_OUTPUT_PREFIX=0` for log-only).
+- Add `partition.paths_build.exclude_prefixes` to omit path prefixes from `build-paths` / `start` while keeping files runnable outside polyrun.
+- Add `Polyrun::RSpec.install_example_debug!`, `install_example_timeout!`, `install_example_rails_logging!`, `install_example_prosopite!` (`POLYRUN_EXAMPLE_DEBUG=1` and related env vars).
+- Add `Polyrun::RSpec.install_sharded_formatter_compat!` for progress formatters (e.g. Fuubar) under `POLYRUN_SHARD_*`.
+
 ## 2.1.2 (2026-07-05)
 
 - Fix per-example timing JSON when RSpec supplies `absolute_file_path` metadata; fix formatter registration when `install_example_timing!` uses a custom output path.

data/CONTRIBUTING.md

@@ -27,6 +27,7 @@ Run the suite under alternate Ruby constraints (see `Appraisals` and `gemfiles/`
 ```bash
 bundle exec appraisal ruby32 rspec
 bundle exec appraisal ruby34 rspec
+bundle exec appraisal ruby40 rspec
 ```
 
 ## Linting

data/docs/SETUP_PROFILE.md

@@ -44,11 +44,40 @@ Rule: anything expensive (compile, `yarn`, Playwright download) belongs in prepa
 |--------|---------|
 | Plain glob | `partition.paths_build.all_glob: spec/**/*_spec.rb` and empty or minimal `stages` |
 | Ordered stages | `partition.paths_build.stages`: regex (e.g. slow integration first) or `sort_by_substring_order` for stable ordering |
+| Exclude prefixes | `partition.paths_build.exclude_prefixes`: omit paths (e.g. `spec/benchmark/`) from `paths_file` while keeping them runnable outside polyrun |
 
 `paths_build` controls **membership** in `partition.paths_file`, not shard assignment order. Default `round_robin` sorts paths alphabetically before mod assignment. Use `strategy: preserve_order_round_robin` to honor paths-file line order. Set `partition.timing_file` without `strategy` to auto-select `cost_binpack`; use `lazy_robin` for round-robin assignment with timing diagnostics.
 
 Refresh list: `polyrun -c polyrun.yml build-paths` (also runs automatically before `plan` / `run-shards` when configured).
 
+## 5b. Parallel worker logs (opt-in)
+
+When `run-shards` fans out multiple workers, stdout/stderr interleave on the parent TTY by default.
+
+| Env | Effect |
+|--------|--------|
+| `POLYRUN_WORKER_OUTPUT_ROUTING=1` | Route each worker through per-shard log files (default dir `tmp/polyrun/workers`) |
+| `POLYRUN_WORKER_LOG_DIR` | Custom log directory (also enables routing when set) |
+| `POLYRUN_WORKER_OUTPUT_ROUTING=0` | Force inherited stdio even when log dir is set |
+| `POLYRUN_WORKER_OUTPUT_PREFIX=0` | Write logs only; no live prefixed TTY echo |
+
+Carriage-return progress chunks (Fuubar-style) pass through unprefixed on the TTY and in logs.
+
+## 5c. RSpec example debug (local investigation)
+
+Orchestration tracing stays on `DEBUG=1` / `POLYRUN_DEBUG=1`. Per-example tooling is separate:
+
+| Env | Effect |
+|--------|--------|
+| `POLYRUN_EXAMPLE_DEBUG=1` | Enable example debug installers |
+| `POLYRUN_DEBUG_SQL=1` or `DEBUG_SQL=1` | Log mutating SQL |
+| `POLYRUN_DEBUG_TRACE=1` or `DEBUG_TRACE=1` | TracePoint under app root |
+| `DEBUG_PROSOPITE=1` | Prosopite N+1 scan when gem is loaded |
+| `DEBUG_LOG_LEVEL` | Rails / ActiveRecord logger severity: `debug`, `info`, `warn`, `error`, `fatal`, or Ruby Logger integers (`0` debug … `4` fatal); default `debug` |
+| `RSPEC_EXAMPLE_TIMEOUT_SEC` | Per-example timeout (disabled while example debug is on) |
+
+In `spec_helper` / `spec/support`: `require "polyrun/rspec"` then `Polyrun::RSpec.install_example_debug!`, `install_example_rails_logging!`, `install_example_timeout!`, and `install_sharded_formatter_compat!` when using Fuubar under `POLYRUN_SHARD_*`. Pair with `install_worker_ping!` for idle timeouts.
+
 ## 6. Coverage and CI reports
 
 | Field | Options |

data/lib/polyrun/cli/help.rb

@@ -23,6 +23,9 @@ module Polyrun
           Parallel workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start). CI local processes per job: POLYRUN_SHARD_PROCESSES or ci-shard --shard-processes (not POLYRUN_WORKERS)
           Per-worker wall timeout: --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC. Exit 124; parent stops remaining workers.
           Per-worker idle timeout: --worker-idle-timeout SEC or POLYRUN_WORKER_IDLE_TIMEOUT_SEC after a progress ping (POLYRUN_WORKER_PING_FILE). Enable pings in test setup. Exit 125. Optional periodic pings: POLYRUN_WORKER_PING_THREAD=1 (POLYRUN_WORKER_PING_INTERVAL_SEC).
+          Worker output routing (opt-in): POLYRUN_WORKER_OUTPUT_ROUTING=1 or POLYRUN_WORKER_LOG_DIR; per-shard logs under tmp/polyrun/workers (POLYRUN_WORKER_OUTPUT_PREFIX=0 for log-only)
+          Example debug (RSpec, opt-in): POLYRUN_EXAMPLE_DEBUG=1; POLYRUN_DEBUG_SQL / POLYRUN_DEBUG_TRACE
+          Sharded formatter compat: progress formatters (e.g. Fuubar) under POLYRUN_SHARD_* (see docs/SETUP_PROFILE.md)
           Orchestration warnings on process stderr: POLYRUN_ORCHESTRATION_STDERR=1
           Spec quality (opt-in): POLYRUN_SPEC_QUALITY=1; run-shards --merge-spec-quality; merge-spec-quality / report-spec-quality
           Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental; see partition.timing_granularity)

data/lib/polyrun/cli/run_queue_command.rb

@@ -3,6 +3,7 @@ require "optparse"
 require "shellwords"
 
 require_relative "../queue/duration"
+require_relative "../queue/worker_loop"
 
 module Polyrun
   class CLI
@@ -83,44 +84,16 @@ module Polyrun
         workers.times do |i|
           wid = "worker-#{i}"
           pid = Process.fork do
-            run_queue_worker_loop(store: store, worker_id: wid, batch: batch, cmd: cmd, on_failure: on_failure)
+            result = Polyrun::Queue::WorkerLoop.run(
+              store: store, worker_id: wid, batch: batch, cmd: cmd, on_failure: on_failure
+            )
+            exit result[:exit_code]
           end
           pids << {pid: pid, worker_id: wid}
         end
         pids
       end
 
-      def run_queue_worker_loop(store:, worker_id:, batch:, cmd:, on_failure:)
-        batches_ok = 0
-        batches_fail = 0
-        loop do
-          claim = store.claim!(worker_id: worker_id, batch_size: batch)
-          paths = claim["paths"] || []
-          break if paths.empty?
-
-          code = run_queue_run_batch(cmd, paths)
-          if code == 0
-            store.ack!(lease_id: claim["lease_id"], worker_id: worker_id)
-            batches_ok += 1
-          elsif on_failure.to_s == "requeue"
-            store.reclaim_lease!(claim["lease_id"])
-            batches_fail += 1
-            exit 1
-          else
-            batches_fail += 1
-            exit code.zero? ? 1 : code
-          end
-        end
-        exit 0
-      rescue Polyrun::Error => e
-        Polyrun::Log.warn "polyrun run-queue worker #{worker_id}: #{e.message}"
-        exit 2
-      end
-
-      def run_queue_run_batch(cmd, paths)
-        system(*cmd, *paths) ? 0 : ($?.exitstatus || 1)
-      end
-
       def run_queue_wait_workers(pids, store:, on_failure:)
         ok = 0
         fail = 0

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 
+require_relative "../worker_output"
 require_relative "run_shards_parallel_wait"
 
 module Polyrun
@@ -22,6 +23,7 @@ module Polyrun
         mt = ctx[:matrix_shard_total]
 
         pids = []
+        Polyrun::WorkerOutput.prepare_log_dir! if Polyrun::WorkerOutput.routing_enabled? && parallel
         workers.times do |shard|
           paths = plan.shard(shard)
           if paths.empty?
@@ -60,6 +62,9 @@ module Polyrun
           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
+          if Polyrun::WorkerOutput.routing_enabled? && parallel
+            Polyrun::Log.warn "polyrun run-shards: shard #{shard} log → #{Polyrun::WorkerOutput.log_path_for(shard)}"
+          end
         end
         [pids, nil]
       end
@@ -81,6 +86,8 @@ module Polyrun
       end
 
       def run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+        return Polyrun::WorkerOutput.spawn_worker(child_env, cmd, paths, hook_cfg) if Polyrun::WorkerOutput.routing_enabled?
+
         if hook_cfg.worker_hooks? && !Polyrun::Hooks.disabled?
           Process.spawn(child_env, "sh", "-c", hook_cfg.build_worker_shell_script(cmd, paths))
         else

data/lib/polyrun/cli/run_shards_parallel_wait.rb

@@ -111,6 +111,7 @@ module Polyrun
       end
 
       def run_shards_finalize_reaped_worker!(h, hook_cfg, workers, st, shard_results, after_hook_err)
+        Polyrun::WorkerOutput.finish_worker(h[:pid])
         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}")
@@ -218,6 +219,7 @@ module Polyrun
         _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::WorkerOutput.warn_shard_log(h[:shard])
         Polyrun::Log.warn "polyrun run-shards: idle shard file sample: #{sample}#{suffix}"
         Polyrun::Log.warn "polyrun run-shards: enable per-example worker progress pings in your test setup so idle timeouts reflect real work; exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
       end
@@ -262,6 +264,7 @@ module Polyrun
             ""
           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::WorkerOutput.warn_shard_log(h[:shard])
         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

data/lib/polyrun/cli/run_shards_run.rb

@@ -124,6 +124,7 @@ module Polyrun
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
+        return if Polyrun::WorkerOutput.routing_enabled?
 
         Polyrun::Log.warn "polyrun run-shards: #{pid_count} children running; RSpec output below may be interleaved."
         Polyrun::Log.warn "polyrun run-shards: each worker prints its own summary line; the last \"N examples\" line is not a total across shards."

data/lib/polyrun/cli/run_shards_worker_interrupt.rb

@@ -1,3 +1,5 @@
+require_relative "../worker_output"
+
 module Polyrun
   class CLI
     # SIGINT/SIGTERM handling and non-blocking reap for parallel worker PIDs (used by run-shards / ci-shard fan-out).
@@ -7,12 +9,17 @@ module Polyrun
       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"
+        if Polyrun::WorkerOutput.routing_enabled?
+          Polyrun::Log.warn "polyrun run-shards: per-shard worker logs under #{Polyrun::WorkerOutput.worker_log_directory_label}"
+        else
+          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
       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)
+        Polyrun::WorkerOutput.shutdown_all!
         run_shards_terminate_children!(pids)
         exit(code)
       rescue Interrupt
@@ -23,6 +30,7 @@ module Polyrun
 
       # Send SIGTERM to each worker PID and wait so Ctrl+C / SIGTERM does not leave orphans.
       def run_shards_terminate_children!(pids)
+        Polyrun::WorkerOutput.shutdown_all!
         run_shards_signal_workers_term(pids)
         run_shards_reap_worker_pids_interruptible(pids.map { |h| h[:pid] })
       end

data/lib/polyrun/partition/paths_build.rb

@@ -40,12 +40,20 @@ module Polyrun
 
         pool = glob_under_cwd(all_glob, cwd)
         pool.uniq!
+        pool = reject_exclude_prefixes(pool, pb)
         stages = Array(pb["stages"])
         return sort_paths(pool) if stages.empty?
 
         apply_stages_to_pool(stages, pool, cwd)
       end
 
+      def reject_exclude_prefixes(pool, pb)
+        prefixes = Array(pb["exclude_prefixes"]).map(&:to_s).reject(&:empty?)
+        return pool if prefixes.empty?
+
+        pool.reject { |path| prefixes.any? { |prefix| path.start_with?(prefix) } }
+      end
+
       def apply_stages_to_pool(stages, pool, cwd)
         remaining = Set.new(pool)
         out = []

data/lib/polyrun/queue/worker_loop.rb

@@ -0,0 +1,39 @@
+module Polyrun
+  module Queue
+    # Claim / run / ack loop for +polyrun run-queue+ workers (forked or direct).
+    module WorkerLoop
+      module_function
+
+      def run(store:, worker_id:, batch:, cmd:, on_failure:)
+        batches_ok = 0
+        batches_fail = 0
+        loop do
+          claim = store.claim!(worker_id: worker_id, batch_size: batch)
+          paths = claim["paths"] || []
+          break if paths.empty?
+
+          code = run_batch(cmd, paths)
+          if code == 0
+            store.ack!(lease_id: claim["lease_id"], worker_id: worker_id)
+            batches_ok += 1
+          elsif on_failure.to_s == "requeue"
+            store.reclaim_lease!(claim["lease_id"])
+            batches_fail += 1
+            return {ok: batches_ok, fail: batches_fail, exit_code: 1}
+          else
+            batches_fail += 1
+            return {ok: batches_ok, fail: batches_fail, exit_code: code.zero? ? 1 : code}
+          end
+        end
+        {ok: batches_ok, fail: batches_fail, exit_code: 0}
+      rescue Polyrun::Error => e
+        Polyrun::Log.warn "polyrun run-queue worker #{worker_id}: #{e.message}"
+        {ok: batches_ok, fail: batches_fail, exit_code: 2}
+      end
+
+      def run_batch(cmd, paths)
+        system(*cmd, *paths) ? 0 : ($?.exitstatus || 1)
+      end
+    end
+  end
+end

data/lib/polyrun/rspec/example_debug.rb

@@ -0,0 +1,158 @@
+require "logger"
+require "timeout"
+require_relative "example_debug_instrumentation"
+
+module Polyrun
+  module RSpec
+    # Per-example RSpec debugging for local investigation (SQL, TracePoint, timeouts).
+    #
+    # +POLYRUN_EXAMPLE_DEBUG=1+ enables installers; +DEBUG=1+ / +POLYRUN_DEBUG=1+ trace orchestration only.
+    # +POLYRUN_DEBUG_SQL=1+ or legacy +DEBUG_SQL=1+ logs mutating SQL.
+    # +POLYRUN_DEBUG_TRACE=1+ or legacy +DEBUG_TRACE=1+ traces :call/:raise under the app root.
+    # +DEBUG_LOG_LEVEL+ accepts Ruby Logger severities as integers (0 debug … 4 fatal) or names.
+    module ExampleDebug
+      LOG_LEVEL_BY_NAME = {
+        "debug" => Logger::DEBUG,
+        "info" => Logger::INFO,
+        "warn" => Logger::WARN,
+        "error" => Logger::ERROR,
+        "fatal" => Logger::FATAL
+      }.freeze
+
+      module_function
+
+      def enabled?
+        truthy?(ENV["POLYRUN_EXAMPLE_DEBUG"])
+      end
+
+      def sql_enabled?
+        enabled? && (truthy?(ENV["POLYRUN_DEBUG_SQL"]) || truthy?(ENV["DEBUG_SQL"]))
+      end
+
+      def trace_enabled?
+        enabled? && (truthy?(ENV["POLYRUN_DEBUG_TRACE"]) || truthy?(ENV["DEBUG_TRACE"]))
+      end
+
+      def prosopite_enabled?
+        enabled? && truthy?(ENV["DEBUG_PROSOPITE"])
+      end
+
+      def print_spec_enabled?
+        enabled? && truthy?(ENV["DEBUG_PRINT_SPEC"])
+      end
+
+      def example_timeout_disabled?
+        enabled?
+      end
+
+      def log_level
+        parse_log_level(ENV.fetch("DEBUG_LOG_LEVEL", "debug"))
+      end
+
+      def rails_log_level
+        case log_level
+        when Logger::DEBUG then :debug
+        when Logger::INFO then :info
+        when Logger::WARN then :warn
+        when Logger::ERROR then :error
+        else :fatal
+        end
+      end
+
+      def parse_log_level(raw)
+        normalized = raw.to_s.strip.downcase
+        return LOG_LEVEL_BY_NAME.fetch(normalized) if LOG_LEVEL_BY_NAME.key?(normalized)
+
+        Integer(normalized)
+      rescue ArgumentError
+        Logger::DEBUG
+      end
+
+      def install!(rspec_config: fetch_rspec_configuration!)
+        install_spec_path_helpers!(rspec_config)
+        install_sql_debug!(rspec_config) if sql_enabled?
+        install_trace_debug!(rspec_config) if trace_enabled?
+      end
+
+      def install_rails_logging!(rspec_config: fetch_rspec_configuration!)
+        return unless enabled?
+        return unless defined?(Rails)
+
+        rspec_config.before do |example|
+          group = example.metadata[:example_group]
+          Polyrun::Log.puts "\n\nRunning #{group[:file_path]}:#{group[:line_number]}"
+
+          level = log_level
+          Rails.logger.level = level
+          if defined?(ActiveRecord::Base)
+            ar_logger = Logger.new(Polyrun::Log.stdout)
+            ar_logger.level = level
+            ActiveRecord::Base.logger = ar_logger
+          end
+        end
+      end
+
+      def install_example_timeout!(
+        rspec_config,
+        seconds: ENV.fetch("RSPEC_EXAMPLE_TIMEOUT_SEC", "30").to_f
+      )
+        return if seconds <= 0
+        return if example_timeout_disabled?
+
+        rspec_config.around(:each) do |example|
+          if example.metadata[:benchmark] || example.metadata[:slow]
+            example.run
+          else
+            Timeout.timeout(seconds) { example.run }
+          end
+        rescue Timeout::Error
+          raise "Example timed out after #{seconds}s (#{example.location})"
+        end
+      end
+
+      def install_prosopite!(rspec_config: fetch_rspec_configuration!)
+        return unless prosopite_enabled?
+        return unless defined?(Prosopite) && defined?(Rails)
+
+        log_path = Rails.root.join("tmp", "prosopite_#{Time.current.strftime("%Y%m%d_%H%M%S")}.log")
+        Prosopite.custom_logger = Logger.new(log_path)
+
+        rspec_config.before { Prosopite.scan }
+        rspec_config.after { Prosopite.finish }
+      end
+
+      def install_spec_path_helpers!(rspec_config)
+        rspec_config.before do |example|
+          group = example.metadata[:example_group]
+          spec_file_path = group[:file_path]
+
+          define_singleton_method(:spec_dirname) { File.dirname(spec_file_path) }
+          define_singleton_method(:spec_basename) { File.basename(spec_file_path) }
+
+          if ExampleDebug.print_spec_enabled?
+            Polyrun::Log.puts "\nRunning #{spec_file_path}:#{group[:line_number]}\n"
+          end
+        end
+
+        rspec_config.after do |example|
+          next unless ExampleDebug.print_spec_enabled?
+
+          group = example.metadata[:example_group]
+          Polyrun::Log.puts "\nFinished #{group[:file_path]}:#{group[:line_number]}\n"
+        end
+      end
+
+      def fetch_rspec_configuration!
+        require "rspec/core"
+        ::RSpec.configuration
+      end
+
+      def truthy?(value)
+        return false if value.nil?
+
+        %w[1 true yes on].include?(value.to_s.strip.downcase)
+      end
+      private_class_method :truthy?, :parse_log_level, :fetch_rspec_configuration!
+    end
+  end
+end

data/lib/polyrun/rspec/example_debug_instrumentation.rb

@@ -0,0 +1,73 @@
+module Polyrun
+  module RSpec
+    module ExampleDebug
+      SKIPPED_SQL_PREFIX = /\A(?:SELECT|SET|SHOW|BEGIN|COMMIT|ROLLBACK|RELEASE|SAVEPOINT)/
+
+      module_function
+
+      def install_sql_debug!(rspec_config, io: Polyrun::Log.stdout)
+        return unless defined?(ActiveSupport::Notifications)
+
+        rspec_config.around do |example|
+          subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
+            payload = event.payload[:sql]
+            next unless loggable_sql?(payload)
+
+            line = sql_with_interpolated_binds(payload, event.payload[:type_casted_binds])
+            io.puts "+ #{line}"
+          end
+
+          example.run
+        ensure
+          ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+        end
+      end
+
+      def install_trace_debug!(rspec_config, root: trace_root, io: Polyrun::Log.stdout)
+        require "pp"
+        root_path = File.expand_path(root.to_s)
+        trace = TracePoint.new do |trace_point|
+          if trace_point.event == :call && trace_point.path.to_s.start_with?(root_path)
+            io.puts PP.pp({event: :call, path: "#{trace_point.path}:#{trace_point.lineno}"}, +"")
+          elsif trace_point.event == :raise
+            io.puts PP.pp(
+              {
+                event: :raise,
+                raised_exception: trace_point.raised_exception,
+                path: "#{trace_point.path}:#{trace_point.lineno}",
+                method_id: trace_point.method_id
+              },
+              +""
+            )
+          end
+        end
+
+        rspec_config.around do |example|
+          trace.enable
+          example.run
+        ensure
+          trace.disable
+        end
+      end
+
+      def loggable_sql?(sql)
+        !sql.to_s.match?(SKIPPED_SQL_PREFIX)
+      end
+
+      def sql_with_interpolated_binds(sql, binds)
+        output = sql.to_s.dup
+        Array(binds).each_with_index do |bind, index|
+          output = output.gsub("$#{index + 1}", "'#{bind}'")
+        end
+        output
+      end
+
+      def trace_root
+        return Rails.root.to_s if defined?(Rails)
+
+        Dir.pwd
+      end
+      private_class_method :trace_root
+    end
+  end
+end

data/lib/polyrun/rspec/sharded_formatter_compat.rb

@@ -0,0 +1,34 @@
+module Polyrun
+  module RSpec
+    # Formatter tweaks for progress bars (e.g. Fuubar) under +POLYRUN_SHARD_*+ workers.
+    module ShardedFormatterCompat
+      module_function
+
+      def install!(rspec_config: fetch_rspec_configuration!)
+        return unless sharded_worker?
+
+        rspec_config.silence_filter_announcements = true
+        noop_fuubar_seed! if defined?(Fuubar)
+      end
+
+      def sharded_worker?
+        !ENV["POLYRUN_SHARD_TOTAL"].to_s.strip.empty?
+      end
+
+      def noop_fuubar_seed!
+        return unless defined?(Fuubar)
+
+        Fuubar.class_eval do
+          def seed(_notification)
+          end
+        end
+      end
+
+      def fetch_rspec_configuration!
+        require "rspec/core"
+        ::RSpec.configuration
+      end
+      private_class_method :fetch_rspec_configuration!
+    end
+  end
+end

data/lib/polyrun/rspec.rb

@@ -72,5 +72,39 @@ module Polyrun
 
       Polyrun::WorkerPing.ensure_interval_ping_thread!
     end
+
+    def install_example_debug!(rspec_config: nil)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def install_example_timeout!(rspec_config: nil, seconds: ENV.fetch("RSPEC_EXAMPLE_TIMEOUT_SEC", "30").to_f)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install_example_timeout!(
+        rspec_config || fetch_rspec_configuration!,
+        seconds: seconds
+      )
+    end
+
+    def install_example_rails_logging!(rspec_config: nil)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install_rails_logging!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def install_example_prosopite!(rspec_config: nil)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install_prosopite!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def install_sharded_formatter_compat!(rspec_config: nil)
+      require_relative "rspec/sharded_formatter_compat"
+      Polyrun::RSpec::ShardedFormatterCompat.install!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def fetch_rspec_configuration!
+      require "rspec/core"
+      ::RSpec.configuration
+    end
+    private_class_method :fetch_rspec_configuration!
   end
 end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "2.1.2"
+  VERSION = "2.1.3"
 end

data/lib/polyrun/worker_output.rb

@@ -0,0 +1,159 @@
+require "fileutils"
+require_relative "worker_output_forwarders"
+
+module Polyrun
+  # Routes parallel worker stdout/stderr through per-shard log files with optional prefixed TTY echo.
+  #
+  # Opt-in: +POLYRUN_WORKER_OUTPUT_ROUTING=1+ (or set +POLYRUN_WORKER_LOG_DIR+).
+  # +POLYRUN_WORKER_OUTPUT_ROUTING=0+ keeps inherited stdio (default polyrun behavior).
+  # +POLYRUN_WORKER_OUTPUT_PREFIX=0+ writes logs only (no live prefixed echo).
+  module WorkerOutput
+    module_function
+
+    def routing_enabled?
+      return false if disabled_by_env?
+
+      truthy?(ENV["POLYRUN_WORKER_OUTPUT_ROUTING"]) || !log_directory.nil?
+    end
+
+    def log_directory
+      value = ENV["POLYRUN_WORKER_LOG_DIR"]
+      return nil if value.nil?
+
+      stripped = value.to_s.strip
+      stripped.empty? ? nil : stripped
+    end
+
+    def prefix_live?
+      return true if ENV["POLYRUN_WORKER_OUTPUT_PREFIX"].nil?
+
+      truthy?(ENV["POLYRUN_WORKER_OUTPUT_PREFIX"])
+    end
+
+    def log_path_for(shard)
+      File.expand_path("shard-#{shard}.log", log_directory || default_log_directory)
+    end
+
+    def worker_log_directory_label
+      log_directory || default_log_directory
+    end
+
+    def prepare_log_dir!
+      directory = log_directory || default_log_directory
+      FileUtils.mkdir_p(directory)
+      Dir.glob(File.join(directory, "shard-*.log")).each { |path| File.delete(path) }
+    end
+
+    def warn_shard_log(shard)
+      return unless routing_enabled?
+
+      Polyrun::Log.warn "polyrun run-shards: shard #{shard} worker log → #{log_path_for(shard)}"
+    end
+
+    def spawn_worker(child_env, cmd, paths, hook_cfg)
+      shard = child_env.fetch("POLYRUN_SHARD_INDEX", "?")
+      out_read, out_write = IO.pipe
+      err_read, err_write = IO.pipe
+
+      pid =
+        if hook_cfg.worker_hooks? && !Polyrun::Hooks.disabled?
+          Process.spawn(
+            child_env,
+            "sh",
+            "-c",
+            hook_cfg.build_worker_shell_script(cmd, paths),
+            out: out_write,
+            err: err_write
+          )
+        else
+          Process.spawn(child_env, *cmd, *paths, out: out_write, err: err_write)
+        end
+
+      out_write.close
+      err_write.close
+
+      start_forwarders(
+        pid: pid,
+        shard: shard,
+        stdout_io: out_read,
+        stderr_io: err_read,
+        log_path: log_path_for(shard)
+      )
+      pid
+    end
+
+    def start_forwarders(pid:, shard:, stdout_io:, stderr_io:, log_path:)
+      forwarder = WorkerForwarder.new(
+        shard: shard,
+        pid: pid,
+        log_path: log_path,
+        prefix_live: prefix_live?
+      )
+      threads = [
+        forwarder_thread(stdout_io, forwarder, :stdout),
+        forwarder_thread(stderr_io, forwarder, :stderr)
+      ]
+      registry[pid] = {threads: threads, ios: [stdout_io, stderr_io], forwarder: forwarder}
+    end
+
+    def finish_worker(pid)
+      entry = registry.delete(pid)
+      return unless entry
+
+      drain_forwarders(entry)
+    end
+
+    def shutdown_all!
+      registry.each_value { |entry| drain_forwarders(entry) }
+      registry.clear
+    end
+
+    def default_log_directory
+      "tmp/polyrun/workers"
+    end
+
+    def disabled_by_env?
+      %w[0 false no off].include?(ENV["POLYRUN_WORKER_OUTPUT_ROUTING"].to_s.strip.downcase)
+    end
+
+    def truthy?(value)
+      return false if value.nil?
+
+      %w[1 true yes on].include?(value.to_s.strip.downcase)
+    end
+    private_class_method :truthy?
+
+    # rubocop:disable ThreadSafety/ClassInstanceVariable -- per-parent-process worker forwarder registry
+    def registry
+      @registry ||= {}
+    end
+    private_class_method :registry
+    # rubocop:enable ThreadSafety/ClassInstanceVariable
+
+    def forwarder_thread(io, forwarder, stream)
+      # rubocop:disable ThreadSafety/NewThread -- one reader thread per worker pipe
+      Thread.new do
+        loop do
+          forwarder.consume(stream, io.readpartial(4096))
+        end
+      rescue IOError, Errno::EPIPE
+        # worker closed the pipe
+      ensure
+        io.close unless io.closed?
+      end
+      # rubocop:enable ThreadSafety/NewThread
+    end
+    private_class_method :forwarder_thread
+
+    def drain_forwarders(entry)
+      entry[:ios].each do |io|
+        io.close unless io.closed?
+      rescue IOError
+        nil
+      end
+      entry[:threads].each(&:join)
+      entry[:forwarder].close
+    end
+    private_class_method :drain_forwarders
+  end
+end

data/lib/polyrun/worker_output_forwarders.rb

@@ -0,0 +1,90 @@
+require "time"
+
+module Polyrun
+  module WorkerOutput
+    class LineForwarder
+      def initialize(shard:, pid:, log_io:, prefix_live:, tty_io:)
+        @shard = shard
+        @pid = pid
+        @log_io = log_io
+        @prefix_live = prefix_live
+        @tty_io = tty_io
+        @buffer = +""
+        @mutex = Mutex.new
+      end
+
+      def consume(chunk)
+        return if chunk.nil? || chunk.empty?
+
+        @mutex.synchronize do
+          if progress_chunk?(chunk)
+            write_tty(chunk)
+            @log_io&.write(chunk)
+            return
+          end
+
+          @buffer << chunk
+          while (newline_index = @buffer.index("\n"))
+            emit_line(@buffer.slice!(0, newline_index + 1))
+          end
+        end
+      end
+
+      def flush
+        @mutex.synchronize do
+          next if @buffer.empty?
+
+          emit_line(@buffer)
+          @buffer.clear
+        end
+      end
+
+      private
+
+      def progress_chunk?(chunk)
+        chunk.include?("\r") && !chunk.include?("\n")
+      end
+
+      def emit_line(line)
+        prefixed = "#{prefix}#{line}"
+        @log_io&.write(prefixed)
+        write_tty(prefixed) if @prefix_live
+      end
+
+      def prefix
+        "[#{Time.now.strftime("%Y-%m-%dT%H:%M:%S")} shard=#{@shard} pid=#{@pid}] "
+      end
+
+      def write_tty(text)
+        @tty_io.write(text)
+        @tty_io.flush
+      end
+    end
+
+    class WorkerForwarder
+      def initialize(shard:, pid:, log_path:, prefix_live:)
+        @shard = shard
+        @pid = pid
+        @log_io = File.open(log_path, "wb")
+        @stdout = LineForwarder.new(shard: shard, pid: pid, log_io: @log_io, prefix_live: prefix_live, tty_io: Polyrun::Log.stdout)
+        @stderr = LineForwarder.new(shard: shard, pid: pid, log_io: @log_io, prefix_live: prefix_live, tty_io: Polyrun::Log.stderr)
+        @write_mutex = Mutex.new
+      end
+
+      def consume(stream, chunk)
+        @write_mutex.synchronize do
+          case stream
+          when :stdout then @stdout.consume(chunk)
+          when :stderr then @stderr.consume(chunk)
+          end
+        end
+      end
+
+      def close
+        @stdout.flush
+        @stderr.flush
+        @log_io.close
+      end
+    end
+  end
+end

data/sig/polyrun/rspec.rbs

@@ -7,5 +7,15 @@ module Polyrun
     def self.install_failure_fragments!: (?only_if: untyped?) -> void
 
     def self.install_worker_ping!: () -> void
+
+    def self.install_example_debug!: (?rspec_config: untyped?) -> void
+
+    def self.install_example_timeout!: (?rspec_config: untyped?, ?seconds: Float) -> void
+
+    def self.install_example_rails_logging!: (?rspec_config: untyped?) -> void
+
+    def self.install_example_prosopite!: (?rspec_config: untyped?) -> void
+
+    def self.install_sharded_formatter_compat!: (?rspec_config: untyped?) -> void
   end
 end

data/sig/polyrun/worker_output.rbs

@@ -0,0 +1,11 @@
+module Polyrun
+  module WorkerOutput
+    def self.routing_enabled?: () -> bool
+    def self.log_path_for: (Integer | String shard) -> String
+    def self.prepare_log_dir!: () -> void
+    def self.warn_shard_log: (Integer | String shard) -> void
+    def self.spawn_worker: (Hash[Symbol, untyped] child_env, Array[String] cmd, Array[String] paths, untyped hook_cfg) -> Integer
+    def self.finish_worker: (Integer pid) -> void
+    def self.shutdown_all!: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.1.3
 platform: ruby
 authors:
 - Andrei Makarov
@@ -266,6 +266,7 @@ files:
 - lib/polyrun/queue/duration.rb
 - lib/polyrun/queue/file_store.rb
 - lib/polyrun/queue/file_store_pending.rb
+- lib/polyrun/queue/worker_loop.rb
 - lib/polyrun/quick.rb
 - lib/polyrun/quick/assertions.rb
 - lib/polyrun/quick/errors.rb
@@ -281,6 +282,9 @@ files:
 - lib/polyrun/reporting/rspec_failure_fragment_formatter.rb
 - lib/polyrun/reporting/rspec_junit.rb
 - lib/polyrun/rspec.rb
+- lib/polyrun/rspec/example_debug.rb
+- lib/polyrun/rspec/example_debug_instrumentation.rb
+- lib/polyrun/rspec/sharded_formatter_compat.rb
 - lib/polyrun/spec_quality.rb
 - lib/polyrun/spec_quality/config.rb
 - lib/polyrun/spec_quality/fragment.rb
@@ -303,6 +307,8 @@ files:
 - lib/polyrun/timing/summary.rb
 - lib/polyrun/timing/variance_report.rb
 - lib/polyrun/version.rb
+- lib/polyrun/worker_output.rb
+- lib/polyrun/worker_output_forwarders.rb
 - lib/polyrun/worker_ping.rb
 - polyrun.gemspec
 - sig/polyrun.rbs
@@ -313,6 +319,7 @@ files:
 - sig/polyrun/minitest.rbs
 - sig/polyrun/quick.rbs
 - sig/polyrun/rspec.rbs
+- sig/polyrun/worker_output.rbs
 - sig/polyrun/worker_ping.rbs
 homepage: https://github.com/amkisko/polyrun.rb
 licenses: