polyrun 2.1.0 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab4d8c8553db3e8e62e83967c9090fc7e788c994d450febb0dc64d39d946f3b
-  data.tar.gz: 3edbc34c324880653c8fd6d7675a31193adfebb0f0a4439d33f74e4ab9d1c327
+  metadata.gz: 4a5cd4e5af5195cb25ca3185b3e828556746f21a6911f8a60f1b43b5b6a316d0
+  data.tar.gz: 67362c68f463339cfd8a66e665b9fb6a5f75cf8ed6276e1a846c68147a27e848
 SHA512:
-  metadata.gz: 1e372f737bf9d8cf76d39979f87dec6acd33e325ef1b5355acdbdb588d9542bc94d0fa0236eecb6632152c0b148560e489a9e26132bede885ddbb73628fa3830
-  data.tar.gz: c61bedba0ea3f6399ffee3d217d719182de6c3e945fbbb14aea9c811f0b75e7e968b7e30a30162fb944635a949629e0102976d0f01e2851411b7694649ac8c5f
+  metadata.gz: b7f7ff8592774bfb1bd173753f5c3cca77d99a392a9dbabdd0bf11c85b510a3dc4cf0c2a66912cf5d48384445e74039a2cfa296d6aeb40b5d008aa575700ef0b
+  data.tar.gz: 05aad7cb17b505112548d072895d56c88f885f07b31e3052ab12e5b4ab0979a555bdf9872380107a60211a8bd54dbd176b98a8970eaba7756fa2e87f8a475a15

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 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.
+
+## 2.1.1 (2026-07-05)
+
+- Fix HTML coverage report `Encoding::CompatibilityError` when source files contain UTF-8; read templates, assets, and source lines as UTF-8 in `formatters_html.rb`.
+
 ## 2.1.0 (2026-07-03)
 
 - Add experimental per-example spec quality (`Polyrun::SpecQuality`): `POLYRUN_SPEC_QUALITY=1`, worker JSONL fragments, `merge-spec-quality`, `report-spec-quality`, and `run-shards --merge-spec-quality`.

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/coverage_commands.rb

@@ -92,7 +92,7 @@ module Polyrun
       def merge_coverage_after_shards(output:, format_list:, config_path:)
         files = merge_coverage_fragment_json_files
         if files.empty?
-          Polyrun::Log.warn "polyrun run-shards: --merge-coverage: no coverage/polyrun-fragment-*.json found (enable Polyrun coverage in spec_helper?)"
+          Polyrun::Log.warn "polyrun run-shards: --merge-coverage: no coverage fragments found under coverage (enable coverage collection in your test setup)"
           return 0
         end
 

data/lib/polyrun/cli/failure_commands.rb

@@ -57,7 +57,7 @@ module Polyrun
         pattern = Polyrun::Reporting::FailureMerge.default_fragment_glob
         files = Dir.glob(pattern).sort
         if files.empty?
-          Polyrun::Log.warn "polyrun run-shards: --merge-failures: no #{Polyrun::Reporting::FailureMerge::FRAGMENT_GLOB} under fragment dir (enable Polyrun::RSpec.install_failure_fragments! in spec_helper?)"
+          Polyrun::Log.warn "polyrun run-shards: --merge-failures: no failure fragments found under tmp/polyrun_failures (enable failure fragments in your test setup)"
           return nil
         end
 

data/lib/polyrun/cli/help.rb

@@ -13,21 +13,22 @@ module Polyrun
             -h, --help
 
           Trace timing (stderr): DEBUG=1 or POLYRUN_DEBUG=1
-          Branch coverage in JSON fragments: POLYRUN_COVERAGE_BRANCHES=1 (stdlib Coverage; merge-coverage merges branches)
-          polyrun quick coverage: POLYRUN_COVERAGE=1 or (config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips
-          Merge wall time (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
+          Coverage: POLYRUN_COVERAGE=1 (or config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips; POLYRUN_COVERAGE_BRANCHES=1 for branch data in fragments
+          Merge profiling (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
           Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html)
-          Skip optional script/build_spec_paths.rb before start: POLYRUN_SKIP_BUILD_SPEC_PATHS=1
-          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)
-          Failure fragments (run-shards --merge-failures): POLYRUN_MERGE_FAILURES=1; parent sets POLYRUN_FAILURE_FRAGMENTS=1 in workers; POLYRUN_FAILURE_FRAGMENT_DIR, POLYRUN_MERGED_FAILURES_OUT, POLYRUN_MERGED_FAILURES_FORMAT; after_suite sets POLYRUN_MERGED_FAILURES_PATH when merge ran
-          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)
-          Per-worker wall timeout: run-shards --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC (max time since each worker spawn). Parent polls all live workers together. Exit 124; remaining workers stopped.
-          Per-worker idle timeout: --worker-idle-timeout SEC or POLYRUN_WORKER_IDLE_TIMEOUT_SEC counts only after a successful ping timestamp (positive float in POLYRUN_WORKER_PING_FILE); empty or unreadable pings do not satisfy idle enforcement—use wall timeout until the first ping. RSpec/Minitest/Quick installers call Polyrun::WorkerPing.ping! per example/suite. Ping files live under tmp/polyrun/ (gitignored via tmp/); parent unlinks each after its worker exits. Exit 125. Optional outer cap: --worker-timeout (exit 124). Optional periodic pings: POLYRUN_WORKER_PING_THREAD=1 (POLYRUN_WORKER_PING_INTERVAL_SEC); WorkerPing.ensure_interval_ping_thread! (installers invoke it—call yourself if wiring workers without install_worker_ping!).
-          If Polyrun::Log.stderr is null or redirected away, set POLYRUN_ORCHESTRATION_STDERR=1 to also print timeout/SIGINT summary lines to process stderr.
-          Spec quality (opt-in): POLYRUN_SPEC_QUALITY=1; per-example JSONL fragments; POLYRUN_SPEC_QUALITY_SAMPLE=0.0-1.0 (default 1.0); POLYRUN_SPEC_QUALITY_STRICT=1; run-shards --merge-spec-quality sets POLYRUN_SPEC_QUALITY_FRAGMENTS=1 in workers; merge-spec-quality / report-spec-quality
-          Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
+          Start skips: POLYRUN_SKIP_BUILD_SPEC_PATHS=1, POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
+          Paths build skip: POLYRUN_SKIP_PATHS_BUILD=1
+          Slow merge warning (seconds, default 10; 0 disables): POLYRUN_MERGE_SLOW_WARN_SECONDS
+          Failure merge: run-shards --merge-failures (enable failure fragments in test setup); POLYRUN_MERGE_FAILURES=1, POLYRUN_FAILURE_FRAGMENT_DIR, POLYRUN_MERGED_FAILURES_OUT
+          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)
           Partition strategies: round_robin (default, sorted), preserve_order_round_robin (paths-file order), lazy_robin (sorted RR + timing diagnostics), cost_binpack (LPT), hrw. partition.timing_file without strategy implies cost_binpack.
 
           commands:
@@ -45,7 +46,7 @@ module Polyrun
             init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
             queue                file-backed batch queue: init (optional --shard/--total etc. as plan, then claim/ack/reclaim/status --json)
             run-queue            init queue and run N workers that claim batches until drained
-            quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
+            quick                quick test runner (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
             hook run <phase>     run one shell hook from polyrun.yml hooks: (e.g. before_suite); optional --shard/--total
             report-coverage      write all coverage formats from one JSON file
             report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)
@@ -53,7 +54,7 @@ module Polyrun
             merge-timing         merge polyrun_timing_*.json shards
             merge-spec-quality   merge polyrun-spec-quality-fragment-*.jsonl shards
             report-spec-quality  spec quality report from merged JSON (zero-hit, hot lines, churn)
-            config               print effective config by dotted path (see Polyrun::Config::Effective; same tree as YAML plus merged prepare.env, resolved partition shard fields, workers)
+            config               print effective config by dotted path (loaded YAML plus merged prepare.env, resolved partition shard fields, workers)
             env                  print shard + database env (see polyrun.yml databases)
             db:setup-template    migrate template DB (PostgreSQL)
             db:setup-shard       CREATE DATABASE shard FROM template (one POLYRUN_SHARD_INDEX)

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

@@ -2,6 +2,10 @@
 module Polyrun
   class CLI
     # Wait, wall/idle timeout, and +after_shard+ hooks for parallel workers (+run-shards+ / +ci-shard-*+).
+    #
+    # Per-worker wait states: running → normal_exit | wall_timeout (124) | idle_timeout (125).
+    # When wall or idle caps are set, the multiplex loop polls every live PID each tick so timeouts
+    # apply fairly across shards (not only the worker currently in Process.wait).
     module RunShardsParallelWait
       WORKER_TIMEOUT_EXIT_STATUS = 124
       WORKER_IDLE_TIMEOUT_EXIT_STATUS = 125
@@ -107,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}")
@@ -214,8 +219,9 @@ 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: use Polyrun::RSpec.install_worker_ping! / Polyrun::Minitest.install_worker_ping! (Polyrun Quick calls ping! each example); exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
+        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
 
       def run_shards_wait_or_force_stop_status(pid)
@@ -258,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_plan_options.rb

@@ -48,7 +48,7 @@ module Polyrun
         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("--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("--worker-idle-timeout SEC", Float, "Max seconds since last worker progress ping (POLYRUN_WORKER_PING_FILE); enable pings in test setup; exit 125") { |v| st[:worker_idle_timeout_sec] = v }
         opts.on("--strategy NAME", String) do |v|
           st[:strategy] = v
           st[:strategy_explicit] = true
@@ -61,10 +61,10 @@ module Polyrun
         opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
         opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
         opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
-        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", "After all workers exit, merge failure fragments from tmp/polyrun_failures (requires failure fragments in test setup)") { 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", "After workers exit, merge spec-quality fragments from coverage (enable spec-quality collection in test setup)") { 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

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."
@@ -162,7 +163,7 @@ module Polyrun
           Polyrun::Log.warn "polyrun run-shards: shard #{s} re-run (same spec list, no interleave): #{rerun}"
         end
         unless merge_failures
-          Polyrun::Log.warn "polyrun run-shards: one merged failure report — use run-shards --merge-failures with Polyrun::RSpec.install_failure_fragments!; POLYRUN_MERGED_FAILURES_PATH is set on after_suite when merge runs."
+          Polyrun::Log.warn "polyrun run-shards: for one combined failure report, add --merge-failures (requires failure fragments enabled in your test setup)"
         end
       end
     end

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/cli/spec_quality_commands.rb

@@ -96,7 +96,7 @@ module Polyrun
       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?)"
+          Polyrun::Log.warn "polyrun run-shards: --merge-spec-quality: no spec-quality fragments found under coverage (enable spec-quality collection in your test setup)"
           return nil
         end
 

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

@@ -23,14 +23,14 @@ module Polyrun
         )
         file_list_html = render_html_partial("file_list", file_rows_html: files.map { |file| html_file_list_row(file) }.join("\n"))
         file_sections_html = files.map { |file| render_html_partial("file_section", file: file) }.join("\n")
-        ERB.new(File.read(html_template_path), trim_mode: "-").result_with_hash(
+        ERB.new(File.read(html_template_path, encoding: Encoding::UTF_8), trim_mode: "-").result_with_hash(
           title: CGI.escapeHTML(title.to_s),
           generated_label: html_generated_label(generated_at),
           overview_html: overview_html,
           file_list_html: file_list_html,
           file_sections_html: file_sections_html,
-          stylesheet: File.read(html_stylesheet_path),
-          javascript: File.read(html_javascript_path)
+          stylesheet: File.read(html_stylesheet_path, encoding: Encoding::UTF_8),
+          javascript: File.read(html_javascript_path, encoding: Encoding::UTF_8)
         )
       end
       # rubocop:enable Metrics/AbcSize
@@ -56,7 +56,7 @@ module Polyrun
       end
 
       def render_html_partial(name, locals = {})
-        ERB.new(File.read(html_partial_path(name)), trim_mode: "-").result_with_hash(locals)
+        ERB.new(File.read(html_partial_path(name), encoding: Encoding::UTF_8), trim_mode: "-").result_with_hash(locals)
       end
 
       def html_file_payload(path, file, root)
@@ -152,7 +152,7 @@ module Polyrun
       def html_source_lines(path, fallback_length)
         return Array.new(fallback_length, "") unless File.file?(path.to_s)
 
-        File.readlines(path.to_s, chomp: true)
+        File.readlines(path.to_s, chomp: true, encoding: Encoding::UTF_8)
       rescue Errno::ENOENT, Errno::EACCES, ArgumentError
         Array.new(fallback_length, "")
       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/file_store.rb

@@ -6,6 +6,13 @@ require "time"
 module Polyrun
   module Queue
     # File-backed queue (spec_queue.md): +queue.json+, +pending/*.json+ chunks, +done.jsonl+, +leases.json+ (OS flock).
+    #
+    # Path lifecycle (lease transitions):
+    #   init!           → paths in pending chunks only
+    #   claim!          → pending −batch → active lease in leases.json
+    #   ack!            → lease removed; paths appended to done.jsonl
+    #   reclaim!        → stale or matching lease → paths returned to pending
+    #   reclaim_lease!  → one lease by id → paths returned to pending
     class FileStore
       CHUNK_SIZE = 500
 

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

@@ -21,6 +21,8 @@ module Polyrun
         if output_path
           op = output_path
           Class.new(Polyrun::Timing::RSpecExampleFormatter) do
+            ::RSpec::Core::Formatters.register self, :example_finished, :close
+
             define_method(:timing_output_path) { op }
           end
         else
@@ -70,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/timing/rspec_example_formatter.rb

@@ -1,6 +1,6 @@
 require "json"
 
-require "rspec/core/formatters/base_formatter"
+require "rspec/core/formatters"
 
 module Polyrun
   module Timing
@@ -13,23 +13,23 @@ module Polyrun
     # Or {Polyrun::RSpec.install_example_timing!} (+output_path:+ avoids touching +ENV+).
     #
     # Default output path: +ENV["POLYRUN_EXAMPLE_TIMING_OUT"]+ if set, else +polyrun_timing_examples.json+.
-    class RSpecExampleFormatter < RSpec::Core::Formatters::BaseFormatter
-      RSpec::Core::Formatters.register self, :example_finished, :close
+    class RSpecExampleFormatter
+      ::RSpec::Core::Formatters.register self, :example_finished, :close
 
       def initialize(output)
-        super
+        @output = output
         @times = {}
       end
 
       def example_finished(notification)
         ex = notification.example
-        result = ex.execution_result
-        return if result.pending?
+        return if ex.pending?
 
+        result = ex.execution_result
         t = result.run_time
         return unless t
 
-        path = ex.metadata[:absolute_path]
+        path = example_absolute_path(ex)
         return unless path
 
         line = ex.metadata[:line_number]
@@ -48,6 +48,13 @@ module Polyrun
       def timing_output_path
         ENV["POLYRUN_EXAMPLE_TIMING_OUT"] || "polyrun_timing_examples.json"
       end
+
+      private
+
+      def example_absolute_path(example)
+        metadata = example.metadata
+        metadata[:absolute_file_path] || metadata[:file_path] || metadata[:absolute_path]
+      end
     end
   end
 end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "2.1.0"
+  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.0
+  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: