polyrun 2.2.9 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd372c59e18ffd48e6e53d42240cb4893fd165af0399ca6c50ca8a4d14a74b0e
-  data.tar.gz: 9aaf900fe002008e213c1f8b48b9c7867ad685db79946d72760f40a92c7052f6
+  metadata.gz: a596cf2a374f9aa883e0f8e449a93a02c303cfc4378d9a0ef2e2b7d45f66d776
+  data.tar.gz: bf7047e62fc1f77a0105e1aac00ff1fca794dd74d47a3aef5838c7cb32aff348
 SHA512:
-  metadata.gz: f3ba035a9df88c6722deaf3c632a213fdc11fa94554b260136fe3500e8fbe3e26825b6ef9f59732a07db3d82cf562a09553a14b677f0e8beb0ab50574775806b
-  data.tar.gz: aac4874eb9000f920691c8796c1ee35e91ed7555b4da84d9d9e1cb2fbce8783c3a6de8ef7dd82aaa02f941e55291a04c172a87fcba20ae4cf10f2a45b611a01e
+  metadata.gz: 39862a1442ecb1704ee9e4416841a70905b94a88fd6e191c4ddcfce8ad8ca02993c99802963e72c175e634e20e39595835e87b083379ebffb317117cddc5604b
+  data.tar.gz: 84a45dd40b1b48fcf9c71ba81103e958ab48c23832b069d3fc2f30be96e7897d37468e39677cb9089a8981390a63037165bd9cc1c8cadca2a0dbae841e84b2e6

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## 3.0.0 (2026-11-12)
+
+- Rename `Polyrun::RSpec` to `Polyrun::RSpecSupport` and `Polyrun::Minitest` to `Polyrun::MinitestSupport` (requires `polyrun/rspec_support` / `polyrun/minitest_support`). Hard cut: old constants and require paths are removed (RFC-0007).
+- Fix `Polyrun::Reporting::RspecJunit.install!` raising `NoMethodError` on `configure` when RSpec wiring was already required (`::RSpec` qualification).
+- Add Sus as a first-class suite: `partition.suite: sus`, `test/**/*.rb` globs, auto-detect via `config/sus.rb`, `parallel-sus`, `ci-shard-sus`, and `Polyrun::SusSupport` (RFC-0008).
+- Treat Covered-style `COVERAGE` (non-falsey) as coverage-wanted for `Coverage::Collector` / SusSupport `install_coverage!` (RFC-0008).
+- Classify Sus-style `test/**/*.rb` paths as `:sus` instead of `:quick` during suite inference.
+- Extend `Polyrun::Quick`: `config/polyrun_quick.rb` suite hooks and `add_load_path`, `around`, error-aware `after`, `with` / `subject`, `be` / `be_a` / `raise_exception`, slowest-example summary (RFC-0009).
+
 ## 2.2.9 (2026-11-07)
 
 - Add `Polyrun::Benchmark::Pressure` for load benches: wall/CPU/RSS/heap/GC plus optional storage and network byte deltas, with target ceilings for iterative pressure runs.
@@ -86,8 +95,8 @@
 
 - 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_*`.
+- Add `Polyrun::RSpecSupport.install_example_debug!`, `install_example_timeout!`, `install_example_rails_logging!`, `install_example_prosopite!` (`POLYRUN_EXAMPLE_DEBUG=1` and related env vars).
+- Add `Polyrun::RSpecSupport.install_sharded_formatter_compat!` for progress formatters (e.g. Fuubar) under `POLYRUN_SHARD_*`.
 
 ## 2.1.2 (2026-07-05)
 
@@ -100,7 +109,7 @@
 ## 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`.
-- Add `Polyrun::RSpec.install_spec_quality!`, `Polyrun::Minitest.install_spec_quality!`, and Quick example hooks; `polyrun init --profile spec-quality`.
+- Add `Polyrun::RSpecSupport.install_spec_quality!`, `Polyrun::MinitestSupport.install_spec_quality!`, and Quick example hooks; `polyrun init --profile spec-quality`.
 - Add `Polyrun::Coverage::ExampleDiff` for per-example line hit deltas from `Coverage.peek_result`; record per-example factory counts via `Data::FactoryCounts`.
 - Report zero-hit examples, line churn, hot lines, shard attribution, optional partition hints (`report-spec-quality --plan`), optional CPU/GC/IO profiling (stdlib), and CI gate thresholds in `config/polyrun_spec_quality.yml`.
 - Document spec quality in `docs/SPEC_QUALITY.md`.
@@ -127,13 +136,13 @@
 
 - Add `run-shards --worker-timeout SEC` and `POLYRUN_WORKER_TIMEOUT_SEC` (wall time per worker since spawn); stop stuck workers; record exit 124 for that shard.
 - Add `run-shards --worker-idle-timeout SEC` and `POLYRUN_WORKER_IDLE_TIMEOUT_SEC`; parent reads monotonic timestamps from `POLYRUN_WORKER_PING_FILE`; record exit 125 when the last ping is stale. Idle applies only after a valid positive ping (use wall timeout until the first ping).
-- Add `Polyrun::WorkerPing` (`ping!`, `ensure_interval_ping_thread!` when `POLYRUN_WORKER_PING_THREAD`). Add `Polyrun::RSpec.install_worker_ping!` and `Polyrun::Minitest.install_worker_ping!`; Polyrun Quick calls `WorkerPing.ping!` around each example. Parent creates ping paths under `tmp/polyrun/` and unlinks files after workers exit.
+- Add `Polyrun::WorkerPing` (`ping!`, `ensure_interval_ping_thread!` when `POLYRUN_WORKER_PING_THREAD`). Add `Polyrun::RSpecSupport.install_worker_ping!` and `Polyrun::MinitestSupport.install_worker_ping!`; Polyrun Quick calls `WorkerPing.ping!` around each example. Parent creates ping paths under `tmp/polyrun/` and unlinks files after workers exit.
 - Poll every live shard worker together when timeouts are enabled so idle and wall limits apply to all children, not only the first waiter.
 - Split parallel worker teardown into `RunShardsParallelWait` and `RunShardsWorkerInterrupt`; keep spawn logic in `RunShardsParallelChildren`.
 - Add `Polyrun::Log.orchestration_warn`; when `POLYRUN_ORCHESTRATION_STDERR=1`, copy one line to process `$stderr` if `Log.stderr` is not the same object (custom/null sinks).
 - Wire `env_worker_timeout_sec` / `env_worker_idle_timeout_sec` into `ci-shard-run` plan context. Rescue `Interrupt` around `after_suite` in `run-shards` and `ci-shard` orchestration where suite hooks run.
 - In `Polyrun::Hooks#run_phase`, rescue `Interrupt` for Ruby DSL and shell hook phases (return 130).
-- Document worker timeout, idle ping, and `POLYRUN_ORCHESTRATION_STDERR` in `polyrun help`. Add `sig/polyrun/worker_ping.rbs` and extend `Polyrun::RSpec` / `Polyrun::Minitest` installer signatures.
+- Document worker timeout, idle ping, and `POLYRUN_ORCHESTRATION_STDERR` in `polyrun help`. Add `sig/polyrun/worker_ping.rbs` and extend `Polyrun::RSpecSupport` / `Polyrun::MinitestSupport` installer signatures.
 
 ## 1.4.2 (2026-04-24)
 
@@ -145,7 +154,7 @@
 ## 1.4.1 (2026-04-16)
 
 - Add `polyrun merge-failures` and `run-shards --merge-failures` / `--merge-failures-output` / `--merge-failures-format`; merge per-worker JSONL under `tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl` (or RSpec JSON via `-i`). Run merge after all workers exit, including when a shard failed (`--merge-coverage` still runs only after all shards succeed).
-- Add `Polyrun::Reporting::FailureMerge`, `Polyrun::RSpec.install_failure_fragments!`, and `Polyrun::Reporting::RspecFailureFragmentFormatter`; parent sets `POLYRUN_FAILURE_FRAGMENTS=1` on workers when merge-failures is enabled.
+- Add `Polyrun::Reporting::FailureMerge`, `Polyrun::RSpecSupport.install_failure_fragments!`, and `Polyrun::Reporting::RspecFailureFragmentFormatter`; parent sets `POLYRUN_FAILURE_FRAGMENTS=1` on workers when merge-failures is enabled.
 - Add optional `reporting:` in `polyrun.yml` and `Polyrun::Config#reporting` for merge-failures toggles and paths; honor `POLYRUN_MERGE_FAILURES`, `POLYRUN_MERGED_FAILURES_OUT`, `POLYRUN_MERGED_FAILURES_FORMAT`; set `POLYRUN_MERGED_FAILURES_PATH` for `after_suite` when merge wrote a file.
 - On bad JSONL or non-RSpec JSON, raise `Polyrun::Error` with path and line where applicable; `merge-failures` exits 1 without a full stack trace; a failed merge after successful workers forces `run-shards` exit 1.
 - Fix `run_shards_plan_ready_log` to take `cfg` so debug logging for merge-failures does not raise `NameError`.
@@ -180,11 +189,11 @@
 ## 1.1.0 (2026-04-15)
 
 - Add `ci-shard-run` / `ci-shard-rspec` for matrix-style sharding (one job per `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL`): resolve paths via the same plan as `polyrun plan`, then `exec` the given command with this shard’s paths (unlike `run-shards`, which fans out multiple workers on one host).
-- Add experimental per-example partition timing: `partition.timing_granularity` / `--timing-granularity` (`file` default, `example` for `path:line` items), `POLYRUN_TIMING_GRANULARITY`, merged timing JSON with `absolute_path:line` keys, `TimingKeys.load_costs_json_file`, constraints matching pins/globs on the file part of locators, queue init support, and optional `Polyrun::Timing::RSpecExampleFormatter` plus `Polyrun::RSpec.install_example_timing!`.
+- Add experimental per-example partition timing: `partition.timing_granularity` / `--timing-granularity` (`file` default, `example` for `path:line` items), `POLYRUN_TIMING_GRANULARITY`, merged timing JSON with `absolute_path:line` keys, `TimingKeys.load_costs_json_file`, constraints matching pins/globs on the file part of locators, queue init support, and optional `Polyrun::Timing::RSpecExampleFormatter` plus `Polyrun::RSpecSupport.install_example_timing!`.
 - Add `Polyrun::ProcessStdio.inherit_stdio_spawn_wait` and `spawn_wait` for subprocesses with inherited stdio (or temp-file capture when `silent: true`) to avoid Open3 pipe-thread noise on interrupt; used by prepare (shell / custom assets), `Prepare::Assets.precompile!`, and `Provision.prepare_template!` (`bin/rails db:prepare`). On failure, `db:prepare` / `assets:precompile` embed captured stdout/stderr in `Polyrun::Error` (truncated when huge).
 - Refactor `polyrun plan` around `plan_command_compute_manifest` and `plan_command_build_manifest`; `cmd_plan` output stays aligned with `plan_command_compute_manifest` (tests guard drift).
 - `TimingKeys.load_costs_json_file` accepts optional `root:` for key normalization; warns when two JSON keys normalize to the same entry with different seconds; `TimingKeys.canonical_file_path` / `normalize_locator` resolve directory symlinks so `/var/…` and `/private/var/…` (macOS) map to one key.
-- `Polyrun::RSpec.install_example_timing!(output_path:)` no longer sets `ENV` when an explicit path is passed; formatter uses `timing_output_path` (override or `ENV` / default filename).
+- `Polyrun::RSpecSupport.install_example_timing!(output_path:)` no longer sets `ENV` when an explicit path is passed; formatter uses `timing_output_path` (override or `ENV` / default filename).
 - Fix noisy `IOError` / broken-pipe behavior when interrupting long-running prepare / Rails subprocesses that previously used `Open3.capture3`.
 
 ## 1.0.0 (2026-04-14)

data/README.md

@@ -10,11 +10,11 @@ Running tests in parallel across processes still requires a single merged covera
 
 Polyrun provides:
 
-- Orchestration: `plan`, `run-shards`, and `parallel-rspec` / `parallel-minitest` / `parallel-quick` (run-shards plus merge-coverage), with an optional on-disk queue and constraints for file lists and load balancing. Bare `polyrun` (no subcommand) picks the suite from `partition.suite`, else `partition.paths_file`, else filesystem auto-detect. For **GitHub Actions-style matrix sharding** (one job per global shard), use `ci-shard-run -- …` (any test runner) or `ci-shard-rspec`—not `run-shards` / `parallel-*`, which fan out N workers on one machine.
+- Orchestration: `plan`, `run-shards`, and `parallel-rspec` / `parallel-minitest` / `parallel-sus` / `parallel-quick` (run-shards plus merge-coverage), with an optional on-disk queue and constraints for file lists and load balancing. Bare `polyrun` (no subcommand) picks the suite from `partition.suite`, else `partition.paths_file`, else filesystem auto-detect (Sus when `config/sus.rb` and `test/**/*.rb` exist). For **GitHub Actions-style matrix sharding** (one job per global shard), use `ci-shard-run -- …` (any test runner), `ci-shard-rspec`, or `ci-shard-sus`—not `run-shards` / `parallel-*`, which fan out N workers on one machine.
 - Coverage: merge SimpleCov-compatible JSON fragments; emit JSON, LCOV, Cobertura, or console summaries (you can drop separate SimpleCov merge plugins for this path).
 - CI reporting: JUnit XML from RSpec JSON; slow-file reports from merged timing JSON.
 - Parallel hygiene: asset digest markers, SQL snapshots, YAML fixture batches, and DB URL or shard helpers aligned with `POLYRUN_SHARD_*`.
-- Optional **`polyrun quick`**: `Polyrun::Quick` — nested `describe`, `it` / `test`, `before` / `after`, `let` / `let!`, `expect(x).to …` matchers, `assert_*` (Minitest-like), and optional **`Polyrun::Quick.capybara!`** (extends `Capybara::DSL` when the **capybara** gem is loaded). Stdlib-only in Polyrun itself. Coverage uses the same `Polyrun::Coverage::Collector` path as RSpec when `POLYRUN_COVERAGE=1` or `config/polyrun_coverage.yml` is present (not when `POLYRUN_COVERAGE_DISABLE=1`).
+- Optional **`polyrun quick`**: `Polyrun::Quick` — nested `describe` / `with`, `it` / `test`, `before` / `after` / `around`, `let` / `let!` / `subject`, `expect(x).to …` / `expect { }.to raise_exception`, `assert_*`, optional `config/polyrun_quick.rb` (`before_suite` / `after_suite` / `add_load_path`), and optional **`Polyrun::Quick.capybara!`**. Stdlib-only in Polyrun itself. Coverage when `POLYRUN_COVERAGE=1`, Covered-style `COVERAGE`, or `config/polyrun_coverage.yml` + `POLYRUN_QUICK_COVERAGE=1` (not when `POLYRUN_COVERAGE_DISABLE=1`).
 - No runtime gems in the gemspec: stdlib and vendored pieces only.
 
 Capybara and Playwright stay in your application; Polyrun does not replace browser drivers.
@@ -93,6 +93,7 @@ bin/polyrun ci-shard-run -- bundle exec rspec   # CI matrix: shard plan + append
 bin/polyrun ci-shard-rspec   # same as ci-shard-run -- bundle exec rspec
 bin/polyrun parallel-rspec --workers 5   # run-shards + merge-coverage (default: bundle exec rspec)
 bin/polyrun parallel-minitest --workers 5   # same; default rails test or ruby -I test
+bin/polyrun parallel-sus --workers 5   # same; default bundle exec sus (OS processes; use with config/sus.rb)
 bin/polyrun parallel-quick --workers 5   # same; default bundle exec polyrun quick
 bin/polyrun run-shards --workers 5 --merge-coverage -- bundle exec rspec
 bin/polyrun merge-coverage -i cov1.json -i cov2.json -o merged.json --format json,lcov,cobertura,console
@@ -122,8 +123,8 @@ Runnable Rails demos (multi-DB, Vite, Capybara, Docker, Postgres sketches) live
 
 That single require loads the CLI and core library **without** loading RSpec or Minitest. Optional integrations (use only what your app needs):
 
-- `require "polyrun/rspec"` — `Polyrun::RSpec` registers `ParallelProvisioning` in `before(:suite)` (your app must use RSpec).
-- `require "polyrun/minitest"` — `Polyrun::Minitest` is a thin alias for `ParallelProvisioning.run_suite_hooks!` (does not `require "minitest"`).
+- `require "polyrun/rspec_support"` — `Polyrun::RSpecSupport` registers `ParallelProvisioning` in `before(:suite)` (your app must use RSpec).
+- `require "polyrun/minitest_support"` — `Polyrun::MinitestSupport` is a thin alias for `ParallelProvisioning.run_suite_hooks!` (does not `require "minitest"`).
 - `require "polyrun/reporting/rspec_junit"` — `Polyrun::Reporting::RspecJunit` adds RSpec’s JSON formatter and writes JUnit on exit; RSpec is loaded only inside `RspecJunit.install!`.
 
 | API | Purpose |
@@ -141,8 +142,8 @@ That single require loads the CLI and core library **without** loading RSpec or
 | `Polyrun::Data::FactoryInstrumentation` | Opt-in FactoryBot patch → `FactoryCounts` (after `require "factory_bot"`). |
 | `Polyrun::Data::SqlSnapshot` | PostgreSQL `pg_dump` / `psql` snapshots under `spec/fixtures/sql_snapshots/`. |
 | `Polyrun::Data::FactoryCounts` | Factory/build counters + summary text. |
-| `Polyrun::RSpec` (`require "polyrun/rspec"`) | `install_parallel_provisioning!` → `before(:suite)` hooks. |
-| `Polyrun::Minitest` (`require "polyrun/minitest"`) | `install_parallel_provisioning!` → same as `ParallelProvisioning.run_suite_hooks!` (no Minitest gem dependency). |
+| `Polyrun::RSpecSupport` (`require "polyrun/rspec_support"`) | `install_parallel_provisioning!` → `before(:suite)` hooks. |
+| `Polyrun::MinitestSupport` (`require "polyrun/minitest_support"`) | `install_parallel_provisioning!` → same as `ParallelProvisioning.run_suite_hooks!` (no Minitest gem dependency). |
 | `Polyrun::Reporting::RspecJunit` (`require "polyrun/reporting/rspec_junit"`) | CI: RSpec JSON formatter + JUnit from `install!` (RSpec loaded only there). |
 | `Polyrun::Prepare::Assets` | Digest trees, marker file, `assets:precompile`. |
 | `Polyrun::Database::Shard` | Shard env map, `%{shard}` DB names, URL path suffix for `postgres://`, `mysql2://`, `mongodb://`, etc. |

data/docs/SETUP_PROFILE.md

@@ -44,6 +44,7 @@ Rule: anything expensive (compile, `yarn`, Playwright download) belongs in prepa
 | Field | Options |
 |--------|---------|
 | Plain glob | `partition.paths_build.all_glob: spec/**/*_spec.rb` and empty or minimal `stages` |
+| Sus suite | `partition.suite: sus` (or auto via `config/sus.rb`); default glob `test/**/*.rb`; CLI `parallel-sus` / `ci-shard-sus`; wire `polyrun/sus_support` in `config/sus.rb`. Prefer Polyrun collector fragments for shard merge; do not enable Covered::Sus in the same process |
 | 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 |
 
@@ -77,7 +78,7 @@ Orchestration tracing stays on `DEBUG=1` / `POLYRUN_DEBUG=1`. Per-example toolin
 | `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); on timeout, ActiveRecord connection pools are disconnected so the next example gets fresh connections (any adapter) |
 
-In `spec_helper` / `spec/support`: `require "polyrun/rspec"` then `Polyrun::RSpec.install_sharded_formatter_compat!` (silences per-worker seed/summary/pending under `POLYRUN_SHARD_*`), `install_example_debug!`, `install_example_rails_logging!`, `install_example_prosopite!`, `install_example_timeout!`. Pair with `install_worker_ping!` for idle timeouts.
+In `spec_helper` / `spec/support`: `require "polyrun/rspec_support"` then `Polyrun::RSpecSupport.install_sharded_formatter_compat!` (silences per-worker seed/summary/pending under `POLYRUN_SHARD_*`), `install_example_debug!`, `install_example_rails_logging!`, `install_example_prosopite!`, `install_example_timeout!`. Pair with `install_worker_ping!` for idle timeouts.
 
 ## 6. Coverage and CI reports
 

data/lib/polyrun/cli/ci_shard_run_command.rb

@@ -141,6 +141,37 @@ module Polyrun
         Polyrun::Log.warn "polyrun ci-shard-rspec: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
         ci_shard_run_fanout!(ctx)
       end
+
+      # Same as +ci-shard-run -- bundle exec sus+ with an optional second segment for Sus-only flags:
+      # +polyrun ci-shard-sus [plan options] [-- [sus args]]+
+      def cmd_ci_shard_sus(argv, config_path)
+        sep = argv.index("--")
+        plan_argv = sep ? argv[0...sep] : argv
+        sus_argv = sep ? argv[(sep + 1)..] : []
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
+        paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-sus")
+        return code if code != 0
+
+        cmd = ["bundle", "exec", "sus", *sus_argv]
+
+        if shard_processes <= 1
+          return ci_shard_run_single!(cmd, paths, cfg, pc, config_path)
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-sus: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
+      end
     end
   end
 end

data/lib/polyrun/cli/default_run.rb

@@ -29,6 +29,11 @@ module Polyrun
           return code if code != 0
 
           cmd_parallel_minitest([], config_path)
+        when :sus
+          code = start_bootstrap!(cfg, [], config_path)
+          return code if code != 0
+
+          cmd_parallel_sus([], config_path)
         when :quick
           code = start_bootstrap!(cfg, [], config_path)
           return code if code != 0
@@ -69,7 +74,7 @@ module Polyrun
 
         suite = Polyrun::Partition::Paths.infer_suite_from_paths(expanded)
         if suite == :invalid
-          Polyrun::Log.warn "polyrun: mixing _spec.rb and _test.rb paths in one run is not supported"
+          Polyrun::Log.warn "polyrun: mixing path families in one run is not supported"
           return 2
         end
         if suite.nil?
@@ -88,6 +93,8 @@ module Polyrun
             cmd_start(combined, config_path)
           when :minitest
             cmd_parallel_minitest(combined, config_path)
+          when :sus
+            cmd_parallel_sus(combined, config_path)
           when :quick
             cmd_parallel_quick(combined, config_path)
           else
@@ -119,10 +126,10 @@ module Polyrun
           if File.directory?(abs)
             spec = Dir.glob(File.join(abs, "**", "*_spec.rb")).sort
             test = Dir.glob(File.join(abs, "**", "*_test.rb")).sort
-            quick = Dir.glob(File.join(abs, "**", "*.rb")).sort.reject do |f|
+            other = Dir.glob(File.join(abs, "**", "*.rb")).sort.reject do |f|
               File.basename(f).end_with?("_spec.rb", "_test.rb")
             end
-            spec + test + quick
+            spec + test + other
           elsif /[*?\[]/.match?(p)
             Dir.glob(abs).sort
           elsif File.file?(abs)

data/lib/polyrun/cli/help.rb

@@ -5,7 +5,7 @@ module Polyrun
         Polyrun::Log.puts <<~HELP
           usage: polyrun [global options] [<command> | <paths...>]
 
-          With no command, runs parallel tests for the resolved suite: partition.suite when set; else suite inferred from partition.paths_file; else filesystem auto-detect (RSpec under spec/ before Minitest under test/, then Polyrun Quick). If the first argument is a known subcommand name, it is dispatched. Otherwise, path-like tokens (optionally with run-shards flags such as --workers) shard those files in parallel; see commands below.
+          With no command, runs parallel tests for the resolved suite: partition.suite when set; else suite inferred from partition.paths_file; else filesystem auto-detect (RSpec under spec/, then Sus when config/sus.rb + test/**/*.rb, then Minitest *_test.rb, then Polyrun Quick). If the first argument is a known subcommand name, it is dispatched. Otherwise, path-like tokens (optionally with run-shards flags such as --workers) shard those files in parallel; see commands below.
 
           global:
             -c, --config PATH    polyrun.yml path (or POLYRUN_CONFIG)
@@ -14,7 +14,7 @@ module Polyrun
             -h, --help
 
           Trace timing (stderr): DEBUG=1 or POLYRUN_DEBUG=1
-          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; POLYRUN_COVERAGE_VERBOSE=1 for per-worker and merged console summaries
+          Coverage: POLYRUN_COVERAGE=1 or Covered-style COVERAGE=<report>; (or config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips; POLYRUN_COVERAGE_BRANCHES=1 for branch data in fragments; POLYRUN_COVERAGE_VERBOSE=1 for per-worker and merged console summaries
           Benchmark profiles: POLYRUN_BENCH=1 (stdout); JSON sidecar in tmp/benchmarks/; POLYRUN_BENCH_FORMATS=csv,markdown for extra exports; report-benchmark / bench
           Hooks shell output: POLYRUN_HOOKS_VERBOSE=1 or -v / POLYRUN_VERBOSE=1 (or DEBUG); failures always print
           Merge profiling (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
@@ -45,15 +45,17 @@ module Polyrun
             run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage / --merge-failures / --merge-spec-quality
             parallel-rspec       run-shards + merge-coverage (defaults to: bundle exec rspec after --); no start prepare/DB bootstrap
             parallel-minitest    run-shards + merge-coverage (defaults to: bundle exec rails test or ruby -I test after --); no start prepare/DB bootstrap
+            parallel-sus         run-shards + merge-coverage (defaults to: bundle exec sus after --); no start prepare/DB bootstrap
             parallel-quick       run-shards + merge-coverage (defaults to: bundle exec polyrun quick after --); no start prepare/DB bootstrap
             start                parallel-rspec; auto-runs prepare (shell/assets) and db:setup-* when polyrun.yml configures them; legacy script/build_spec_paths.rb if paths_build absent
             ci-shard-run         CI matrix: build-paths + plan for POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL (or config), then run your command with that shard's paths after --; optional --shard-processes M or --workers M (POLYRUN_SHARD_PROCESSES; not POLYRUN_WORKERS) for N×M jobs × processes on this host
             ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional --shard-processes / --workers / -- [rspec-only flags]
+            ci-shard-sus         same as ci-shard-run -- bundle exec sus; optional --shard-processes / --workers / -- [sus-only flags]
             build-paths          write partition.paths_file from partition.paths_build (same as auto step before plan/run-shards)
             init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
             queue                file-backed batch queue: init (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                quick test runner (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
+            quick                quick test runner (describe/with/it, before/after/around, let/subject, expect…to, assert_*; config/polyrun_quick.rb; 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, CSV, or Markdown

data/lib/polyrun/cli/run_shards_command.rb

@@ -72,6 +72,23 @@ module Polyrun
         cmd_run_shards(combined, config_path)
       end
 
+      # Same as parallel-rspec but runs +bundle exec sus+ after +--+ (one Sus process per shard).
+      # Does not run +start+ prepare/database bootstrap (use +polyrun start+ or bare +polyrun+ for that).
+      # Prefer OS-process shards here when workers need isolated databases; Sus's own +sus-parallel+ is in-process threads.
+      def cmd_parallel_sus(argv, config_path)
+        sep = argv.index("--")
+        combined =
+          if sep
+            head = argv[0...sep]
+            tail = argv[sep..]
+            head + ["--merge-coverage"] + tail
+          else
+            argv + ["--merge-coverage", "--", "bundle", "exec", "sus"]
+          end
+        Polyrun::Debug.log_kv(parallel_sus: "combined argv", argv: combined)
+        cmd_run_shards(combined, config_path)
+      end
+
       def minitest_parallel_cmd
         rails_bin = File.expand_path("bin/rails", Dir.pwd)
         if File.file?(rails_bin)

data/lib/polyrun/cli.rb

@@ -30,14 +30,15 @@ module Polyrun
   class CLI
     CI_SHARD_COMMANDS = {
       "ci-shard-run" => :cmd_ci_shard_run,
-      "ci-shard-rspec" => :cmd_ci_shard_rspec
+      "ci-shard-rspec" => :cmd_ci_shard_rspec,
+      "ci-shard-sus" => :cmd_ci_shard_sus
     }.freeze
 
     # 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 merge-spec-quality report-coverage report-junit report-timing report-spec-quality report-benchmark bench
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
-      run-shards parallel-rspec parallel-minitest parallel-quick start build-paths init queue run-queue quick hook validate doctor
+      run-shards parallel-rspec parallel-minitest parallel-sus parallel-quick start build-paths init queue run-queue quick hook validate doctor
     ].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.
@@ -219,6 +220,8 @@ module Polyrun
         cmd_parallel_rspec(argv, config_path)
       when "parallel-minitest"
         cmd_parallel_minitest(argv, config_path)
+      when "parallel-sus"
+        cmd_parallel_sus(argv, config_path)
       when "parallel-quick"
         cmd_parallel_quick(argv, config_path)
       when "start"

data/lib/polyrun/coverage/collector.rb

@@ -96,11 +96,13 @@ module Polyrun
         instance_variable_defined?(:@config) && @config
       end
 
-      # Whether +polyrun quick+ should call {Rails.start!} before loading quick files: not disabled,
-      # and (+POLYRUN_COVERAGE=1+ or (+config/polyrun_coverage.yml+ exists and +POLYRUN_QUICK_COVERAGE=1+)).
+      # Whether +polyrun quick+ / Sus helpers should call {Rails.start!} / {start!} before loading tests:
+      # not disabled, and (+POLYRUN_COVERAGE=1+ or Covered-style +COVERAGE+ set, or
+      # (+config/polyrun_coverage.yml+ exists and +POLYRUN_QUICK_COVERAGE=1+)).
       def self.coverage_requested_for_quick?(root = Dir.pwd)
         return false if disabled?
-        return true if %w[1 true yes].include?(ENV["POLYRUN_COVERAGE"]&.to_s&.downcase)
+        return true if polyrun_coverage_env_enabled?
+        return true if covered_env_enabled?
 
         path = File.join(File.expand_path(root), "config", "polyrun_coverage.yml")
         return false unless File.file?(path)
@@ -110,6 +112,21 @@ module Polyrun
         %w[1 true yes].include?(ENV["POLYRUN_QUICK_COVERAGE"]&.to_s&.downcase)
       end
 
+      # +POLYRUN_COVERAGE=1/true/yes+.
+      def self.polyrun_coverage_env_enabled?
+        %w[1 true yes].include?(ENV["POLYRUN_COVERAGE"]&.to_s&.downcase)
+      end
+
+      # Covered sets +COVERAGE+ to a report name (e.g. +PartialSummary+) or +true+.
+      # Empty / +0+ / +false+ / +no+ / +off+ stay off.
+      def self.covered_env_enabled?
+        value = ENV["COVERAGE"].to_s
+        return false if value.empty?
+        return false if %w[0 false no off].include?(value.downcase)
+
+        true
+      end
+
       # When +POLYRUN_SHARD_TOTAL+ > 1, each worker only writes the JSON fragment; merged reports
       # (+merge-coverage+ / +report-coverage+) are authoritative. Set +POLYRUN_COVERAGE_WORKER_FORMATS=1+
       # to force per-worker formatter output (debug only; duplicates work N times).
@@ -138,54 +155,9 @@ module Polyrun
         end
         m
       end
-
-      # Normalizes stdlib Coverage.result to merge-compatible file entries (lines; branches when collected).
-      def result_to_blob(raw)
-        out = {}
-        raw.each do |path, cov|
-          next unless cov.is_a?(Hash)
-
-          lines = cov[:lines] || cov["lines"]
-          next unless lines.is_a?(Array)
-
-          entry = {"lines" => lines.map { |x| x }}
-          br = cov[:branches] || cov["branches"]
-          entry["branches"] = br if br
-          out[path.to_s] = entry
-        end
-        out
-      end
-
-      def normalize_blob_paths(blob, root)
-        root = File.expand_path(root)
-        blob.each_with_object({}) do |(path, entry), acc|
-          acc[File.expand_path(path.to_s, root)] = entry
-        end
-      end
-
-      def normalize_groups(groups)
-        return nil if groups.nil?
-
-        h = groups.is_a?(Hash) ? groups : {}
-        return nil if h.empty?
-
-        h.transform_keys(&:to_s).transform_values(&:to_s)
-      end
-
-      def keep_under_root(blob, root, track_under)
-        return blob if track_under.nil? || track_under.empty?
-
-        root = File.expand_path(root)
-        prefixes = track_under.map { |d| File.join(root, d) }
-        blob.each_with_object({}) do |(path, entry), acc|
-          p = path.to_s
-          next unless prefixes.any? { |pre| p == pre || p.start_with?(pre + "/") }
-
-          acc[path] = entry
-        end
-      end
     end
   end
 end
 
+require_relative "collector_blob"
 require_relative "collector_finish"

data/lib/polyrun/coverage/collector_blob.rb

@@ -0,0 +1,53 @@
+module Polyrun
+  module Coverage
+    module Collector
+      module_function
+
+      # Normalizes stdlib Coverage.result to merge-compatible file entries (lines; branches when collected).
+      def result_to_blob(raw)
+        out = {}
+        raw.each do |path, cov|
+          next unless cov.is_a?(Hash)
+
+          lines = cov[:lines] || cov["lines"]
+          next unless lines.is_a?(Array)
+
+          entry = {"lines" => lines.map { |x| x }}
+          br = cov[:branches] || cov["branches"]
+          entry["branches"] = br if br
+          out[path.to_s] = entry
+        end
+        out
+      end
+
+      def normalize_blob_paths(blob, root)
+        root = File.expand_path(root)
+        blob.each_with_object({}) do |(path, entry), acc|
+          acc[File.expand_path(path.to_s, root)] = entry
+        end
+      end
+
+      def normalize_groups(groups)
+        return nil if groups.nil?
+
+        h = groups.is_a?(Hash) ? groups : {}
+        return nil if h.empty?
+
+        h.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      def keep_under_root(blob, root, track_under)
+        return blob if track_under.nil? || track_under.empty?
+
+        root = File.expand_path(root)
+        prefixes = track_under.map { |d| File.join(root, d) }
+        blob.each_with_object({}) do |(path, entry), acc|
+          p = path.to_s
+          next unless prefixes.any? { |pre| p == pre || p.start_with?(pre + "/") }
+
+          acc[path] = entry
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/data/parallel_provisioning.rb

@@ -12,8 +12,8 @@ module Polyrun
     #   # In spec_helper after configure:
     #   Polyrun::Data::ParallelProvisioning.run_suite_hooks!
     #
-    # Or use {Polyrun::RSpec.install_parallel_provisioning!} (+before(:suite)+) or {Polyrun::Minitest.install_parallel_provisioning!}
-    # (+require+ +polyrun/minitest+ from +test/test_helper.rb+).
+    # Or use {Polyrun::RSpecSupport.install_parallel_provisioning!} (+before(:suite)+) or {Polyrun::MinitestSupport.install_parallel_provisioning!}
+    # (+require+ +polyrun/minitest_support+ from +test/test_helper.rb+).
     module ParallelProvisioning
       class Configuration
         attr_accessor :serial_hook, :parallel_worker_hook

data/lib/polyrun/hooks/dsl.rb

@@ -85,6 +85,10 @@ module Polyrun
         end
       end
 
+      # Load-time constant: `||=` can create two monitors.
+      CACHE_MU = Monitor.new
+      private_constant :CACHE_MU
+
       class << self
         # @return [Registry, nil]
         def load_registry(path)
@@ -94,7 +98,7 @@ module Polyrun
           return nil unless File.file?(full)
 
           mtime = File.mtime(full)
-          cache_mu.synchronize do
+          CACHE_MU.synchronize do
             hit = registry_cache[full]
             return hit[:registry] if hit && hit[:mtime] == mtime
 
@@ -108,16 +112,12 @@ module Polyrun
         end
 
         def clear_cache!
-          cache_mu.synchronize { registry_cache.clear }
+          CACHE_MU.synchronize { registry_cache.clear }
         end
 
         private
 
         # rubocop:disable ThreadSafety/ClassInstanceVariable -- single-threaded hook load; Monitor protects cache
-        def cache_mu
-          @cache_mu ||= Monitor.new
-        end
-
         def registry_cache
           @registry_cache ||= {}
         end

data/lib/polyrun/{minitest.rb → minitest_support.rb}

@@ -1,12 +1,12 @@
 require_relative "../polyrun"
 
 module Polyrun
-  # Optional Minitest-oriented wiring (require +polyrun/minitest+ explicitly).
+  # Optional Minitest-oriented wiring (require +polyrun/minitest_support+ explicitly).
   #
   # Does not load the +minitest+ gem. Call {install_parallel_provisioning!} from +test/test_helper.rb+
   # after Rails / DB configuration (same timing as a direct call to
   # {Data::ParallelProvisioning.run_suite_hooks!}).
-  module Minitest
+  module MinitestSupport
     module WorkerPingTestHook
       def setup
         Polyrun::WorkerPing.ping!(location: polyrun_minitest_location)
@@ -35,12 +35,12 @@ module Polyrun
       Polyrun::Data::ParallelProvisioning.run_suite_hooks!
     end
 
-    # Same ping semantics as {RSpec.install_worker_ping!}: +ping!+ at test +setup+ and +teardown+.
+    # Same ping semantics as {RSpecSupport.install_worker_ping!}: +ping!+ at test +setup+ and +teardown+.
     # Requires +minitest+ to be loaded first (+Minitest::Test+ defined).
     def install_worker_ping!
       require_relative "worker_ping"
       unless defined?(::Minitest::Test)
-        Polyrun::Log.warn "polyrun minitest: install_worker_ping! skipped (load minitest/autorun or minitest/test first)"
+        Polyrun::Log.warn "polyrun minitest_support: install_worker_ping! skipped (load minitest/autorun or minitest/test first)"
         return
       end