polyrun 2.2.4 → 2.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de79eaae07044fa991b839a44011f7648df5ba16d0586a1ea2708c1d7160cf5e
-  data.tar.gz: f3cbab3bf642164ffa507aa75be1acaaf7a232057b1b1c5f3fcdb0f804c2a0a7
+  metadata.gz: 69dd2432a149cc9790756d2d54b6481e898604a7ae84219b8b5cfbd65997e231
+  data.tar.gz: ab1ea9013d606dd53e717cc421e353c668b47382871e3494f03fa689333e422c
 SHA512:
-  metadata.gz: f62f0cbc1760e3fc42a4711b7e55eace3b8b5bb038836abcae91eba876cfabf9b72832e2f04a284744fdf09247288bff6b60c7a3b1a38d00ee140d37634702df
-  data.tar.gz: 4f9b6d94992745419d35a5bbb40041094569f725470904f546566bfdba7a3e7eeca899f5b80844d9908ca36e744870fef3f8ecef6e20d589fa090d0363859147
+  metadata.gz: 70c45810383e893e6d4ed8a9b2288f3540bb85e37345149283cd9992e2f23c5fa1d475b9e43766d20ddc6f93eaae562c258ff99769284bf606aa2858bbaae515
+  data.tar.gz: 17a14844465eade2840dcc968d1c432e4462991ac099831cd03cd19f262aec9b42d5bd129efcc8e0b843534357ae281380507efb7c40f530e772a7bcb78d9f40

data/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 2.2.6 (2026-10-29)
+
+- Fix `polyrun start` auto database provision when `databases:` uses a non-Postgres adapter (`mysql2`, trilogy, …): skip CloneShards with a clear warning (or exit 1 if `start.databases: true`); keep `template_db` / `shard_db_pattern` for URL shaping.
+- Fail `db:clone-shards` / `db:setup-shard` before `psql` when the inferred adapter is not PostgreSQL.
+- Pass `postgresql:` host, port, username, and password from `polyrun.yml` into `psql` during shard provision (password via child `PGPASSWORD`).
+- Fix implicit path runs so tokens after `--` stay the worker command, and `--paths-file` is passed before `--`.
+- Accept `polyrun start --workers=N` (equals form) so shard DB provision matches worker count.
+- Reject `databases.shard_db_pattern` without `%{shard}` / `%<shard>d`, and refuse patterns that resolve to `template_db`.
+- Redact database passwords in `db:*` / CloneShards dry-run shell logs.
+- Raise when an explicit `-c` / `POLYRUN_CONFIG` path is missing; map `Polyrun::Error` to exit 2.
+- Validate `run-queue --workers` (1..max) and exit forked queue workers with `exit!`.
+- Fix SpecQuality `minimum_unique_lines_per_example` gate for thresholds above 1; keep only positive or CPU profile deltas.
+- Align file-granularity timing cost keys with realpath normalization so cost binpack hits under symlink roots.
+- TERM shard workers before draining routed worker output on SIGINT/SIGTERM; skip empty queue leases.
+- Recover interrupted queue claim/ack/reclaim via `intent.json`; age leases by `heartbeat_at`; quarantine poison paths after `POLYRUN_QUEUE_MAX_ATTEMPTS` (default 3).
+- On a failed `run-queue` batch, re-run paths one-by-one and ack successes so a poison path does not requeue neighbors.
+- Spawn shard workers in their own process group and signal the group on timeout/interrupt; abort already-started workers if a later spawn fails.
+- Cache coverage HTML ERB templates; fold merge fragments without retaining full JSON documents; share plan/run-shards timing cost resolution.
+- Clarify `run-shards` interleaved-output notice: RSpec summary counts apply to individual shards (no false per-worker total).
+
+## 2.2.5 (2026-09-24)
+
+- Fix bare `polyrun` suite selection when both `spec/` and `test/` exist: honor `partition.suite`, else infer from `partition.paths_file`, else filesystem auto-detect (RSpec first).
+- Exit 2 when `partition.suite` disagrees with `paths_file`, or when `run-shards` paths infer a different suite than a recognizable command after `--`.
+- Add `parallel-minitest` and `parallel-quick` CLI subcommands (same shape as `parallel-rspec`); they do not run `start` prepare or database bootstrap.
+- Recognize `bin/rails test` and compact `ruby -Itest` in the suite/command mismatch guard; strip `path:line` locators before classifying paths.
+- Skip legacy `spec/spec_paths.txt` when `partition.suite` is `minitest` or `quick`; allow mixed path lists only with suite-agnostic custom runners.
+
 ## 2.2.4 (2026-09-04)
 
 - Fix `DEBUG_SQL` / `POLYRUN_DEBUG_SQL` raising `NoMethodError` for `loggable_sql?` when the SQL subscriber runs on an RSpec example group.

data/README.md

@@ -10,7 +10,7 @@ Running tests in parallel across processes still requires a single merged covera
 
 Polyrun provides:
 
-- Orchestration: `plan`, `run-shards`, and `parallel-rspec` (run-shards plus merge-coverage), with an optional on-disk queue and constraints for file lists and load balancing. 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-rspec`, which fan out N workers on one machine.
+- 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.
 - 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_*`.
@@ -92,6 +92,8 @@ bin/polyrun build-paths   # write spec/spec_paths.txt from partition.paths_build
 bin/polyrun ci-shard-run -- bundle exec rspec   # CI matrix: shard plan + append paths to the command after --
 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-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
 bin/polyrun env --shard 0 --total 4   # print DATABASE_URL exports from polyrun.yml in cwd
@@ -145,6 +147,7 @@ That single require loads the CLI and core library **without** loading RSpec or
 | `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. |
 | `Polyrun::Database::UrlBuilder` | URLs from `polyrun.yml` `databases:` — nested blocks or `adapter:` for common Rails stacks (`postgresql`, `mysql`/`mysql2`, `trilogy`, `sqlserver`/`mssql`, `sqlite3`/`sqlite`, `mongodb`/`mongo`). |
+| `Polyrun::Database::CloneShards` / `Provision` | PostgreSQL-only template + shard `CREATE DATABASE … TEMPLATE` via `psql`. Non-Postgres configs still use UrlBuilder for env; set `start.databases: false` and provision shards in prepare. |
 | `Polyrun::Hooks` | Load from `Config#hooks`; `run_phase` / `run_phase_if_enabled`; `build_worker_shell_script` wraps the worker command. |
 | `Polyrun::Hooks::Dsl` | Ruby hook file (`hooks.ruby`); `before(:suite)` / `after(:each)` etc. in `config/polyrun_hooks.rb` (see README). |
 

data/docs/SETUP_PROFILE.md

@@ -25,6 +25,7 @@ Do not mix “fan out N workers inside one job” with “matrix shard index”
 |--------|---------|
 | Single test DB | Omitting `databases:` in `polyrun.yml` may be enough; ensure parallel workers do not share one DB if they mutate data |
 | Multi-DB or shard suffixes | `databases:` in `polyrun.yml` (`shard_db_pattern`, `template_db`, optional `connections` and `env_key`). `database.yml` or `DATABASE_URL` may use `%{shard}` or `POLYRUN_SHARD_INDEX` suffixes—the same convention as `polyrun env` |
+| Non-Postgres adapters (mysql2, trilogy, …) | `UrlBuilder` still emits URLs from `template_db` / `shard_db_pattern`. Auto provision on `polyrun start` and `db:clone-shards` / `db:setup-shard` are PostgreSQL-only (`CREATE DATABASE … TEMPLATE`). For MySQL/MariaDB, set `start.databases: false` (or rely on the skip warning) and provision shards in `prepare` |
 | External provisioning | Sometimes `db:prepare` plus shell clone scripts (multi-DB apps)—document ordering: prepare databases before `run-shards` |
 
 ## 4. Prepare (run once before workers)

data/lib/polyrun/cli/database_commands.rb

@@ -47,26 +47,32 @@ module Polyrun
       def cmd_db_setup_shard(argv, config_path)
         dry = db_setup_shard_parse_options!(argv)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
-        dh = cfg.databases
-        if !dh.is_a?(Hash) || dh.empty?
+        databases = cfg.databases
+        if !databases.is_a?(Hash) || databases.empty?
           Polyrun::Log.warn "db:setup-shard: configure databases: in polyrun.yml"
           return 2
         end
 
+        unless Polyrun::Database::UrlBuilder::ConnectionInfer.postgresql?(databases)
+          adapter = Polyrun::Database::UrlBuilder::ConnectionInfer.infer_adapter_name(databases)
+          Polyrun::Log.warn "db:setup-shard: PostgreSQL-only (databases adapter is #{adapter})"
+          return 2
+        end
+
         shard = resolve_shard_index(cfg.partition)
-        template = dh["template_db"] || dh[:template_db]
+        template = databases["template_db"] || databases[:template_db]
         if !template
           Polyrun::Log.warn "db:setup-shard: set databases.template_db"
           return 2
         end
 
-        plan = Polyrun::Database::UrlBuilder.shard_database_plan(dh, shard_index: shard)
+        plan = Polyrun::Database::UrlBuilder.shard_database_plan(databases, shard_index: shard)
         if plan.empty?
           Polyrun::Log.warn "db:setup-shard: could not derive shard database names from polyrun.yml"
           return 2
         end
 
-        db_setup_shard_run_plan(plan, dry: dry)
+        db_setup_shard_run_plan(plan, databases, dry: dry)
       end
 
       def db_setup_shard_parse_options!(argv)
@@ -77,7 +83,7 @@ module Polyrun
         dry
       end
 
-      def db_setup_shard_run_plan(plan, dry:)
+      def db_setup_shard_run_plan(plan, databases, dry:)
         if dry
           plan.each do |row|
             Polyrun::Log.warn "would: CREATE DATABASE #{row[:new_db]} TEMPLATE #{row[:template_db]}"
@@ -85,11 +91,19 @@ module Polyrun
           return 0
         end
 
+        conn = Polyrun::Database::UrlBuilder::Connection.resolve_connection(databases)
+        opts = {
+          host: conn[:host],
+          port: conn[:port],
+          username: conn[:user],
+          password: conn[:password]
+        }
         threads = plan.map do |row|
           Thread.new do
             Polyrun::Database::Provision.create_database_from_template!(
               new_db: row[:new_db],
-              template_db: row[:template_db].to_s
+              template_db: row[:template_db].to_s,
+              **opts
             )
           end
         end

data/lib/polyrun/cli/default_run.rb

@@ -7,20 +7,32 @@ module Polyrun
       private
 
       def dispatch_default_parallel!(config_path)
-        suite = Polyrun::Partition::Paths.detect_auto_suite(Dir.pwd)
-        unless suite
-          Polyrun::Log.warn "polyrun: no tests found (spec/**/*_spec.rb, test/**/*_test.rb, or Polyrun quick files). See polyrun help."
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
+        return code if code != 0
+
+        resolved = Polyrun::Partition::Suite.resolve_default(cwd: Dir.pwd, partition: pc)
+        if resolved[:error]
+          Polyrun::Log.warn "polyrun: #{resolved[:error]}"
           return 2
         end
 
+        suite = resolved[:suite]
         Polyrun::Log.warn "polyrun: default → parallel #{suite} (use `polyrun help` for subcommands)" if @verbose
 
         case suite
         when :rspec
           cmd_start([], config_path)
         when :minitest
+          code = start_bootstrap!(cfg, [], config_path)
+          return code if code != 0
+
           cmd_parallel_minitest([], config_path)
         when :quick
+          code = start_bootstrap!(cfg, [], config_path)
+          return code if code != 0
+
           cmd_parallel_quick([], config_path)
         else
           2
@@ -48,8 +60,7 @@ module Polyrun
       end
 
       def dispatch_implicit_parallel_targets!(argv, config_path)
-        path_tokens = argv.select { |a| cli_implicit_path_token?(a) }
-        head = argv.reject { |a| cli_implicit_path_token?(a) }
+        path_tokens, head, after = split_implicit_arguments(argv)
         expanded = expand_implicit_target_paths(path_tokens)
         if expanded.empty?
           Polyrun::Log.warn "polyrun: no files matched path arguments"
@@ -70,7 +81,8 @@ module Polyrun
         begin
           tmp.write(expanded.join("\n") + "\n")
           tmp.close
-          combined = head + ["--paths-file", tmp.path]
+          # Keep --paths-file before `--` so OptionParser sees it; after `--` it becomes a worker argv token.
+          combined = head + ["--paths-file", tmp.path] + after
           case suite
           when :rspec
             cmd_start(combined, config_path)
@@ -91,6 +103,16 @@ module Polyrun
         end
       end
 
+      def split_implicit_arguments(argv)
+        # Only tokens before `--` are suite paths; everything from `--` onward is the worker command.
+        sep = argv.index("--")
+        before = sep ? argv[0...sep] : argv
+        after = sep ? argv[sep..] : []
+        path_tokens = before.select { |a| cli_implicit_path_token?(a) }
+        head = before.reject { |a| cli_implicit_path_token?(a) }
+        [path_tokens, head, after]
+      end
+
       def expand_implicit_target_paths(path_tokens)
         path_tokens.flat_map do |p|
           abs = File.expand_path(p)

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 detected suite: RSpec under spec/, Minitest under test/, or Polyrun Quick (same discovery as 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/ 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.
 
           global:
             -c, --config PATH    polyrun.yml path (or POLYRUN_CONFIG)
@@ -40,7 +40,9 @@ module Polyrun
             merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console/html/csv/markdown)
             merge-failures       merge per-shard failure JSONL fragments or RSpec JSON files (jsonl/json/csv/markdown)
             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 --)
+            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-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]

data/lib/polyrun/cli/helpers.rb

@@ -11,6 +11,46 @@ module Polyrun
         Polyrun::Config::Resolver.env_int(name, fallback)
       end
 
+      # Shared timing → costs/strategy resolution for +plan+ and +run-shards+.
+      # @return [Array] +[costs, strategy, error_code]+ where +error_code+ is nil on success
+      def partition_resolve_costs_and_strategy(
+        timing_path,
+        strategy,
+        timing_granularity,
+        strategy_explicit: false,
+        log_prefix: "polyrun"
+      )
+        strategy = strategy.to_s
+        if timing_path
+          if strategy_explicit && strategy == "round_robin"
+            return [nil, strategy, nil]
+          end
+
+          costs = Polyrun::Partition::Plan.load_timing_costs(
+            File.expand_path(timing_path.to_s, Dir.pwd),
+            granularity: timing_granularity
+          )
+          if costs.empty?
+            Polyrun::Log.warn "#{log_prefix}: timing file missing or empty: #{timing_path}"
+            return [nil, nil, 2]
+          end
+          if Polyrun::Partition::Plan.timing_load_strategy?(strategy)
+            return [costs, strategy, nil]
+          end
+          unless strategy_explicit
+            Polyrun::Log.warn "#{log_prefix}: using cost_binpack (timing data present)" if @verbose
+            return [costs, "cost_binpack", nil]
+          end
+
+          [nil, strategy, nil]
+        elsif Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.lazy_robin_strategy?(strategy)
+          Polyrun::Log.warn "#{log_prefix}: --timing or partition.timing_file required for strategy #{strategy}"
+          [nil, nil, 2]
+        else
+          [nil, strategy, nil]
+        end
+      end
+
       # Per-worker wall clock (from spawn) for run-shards / ci-shard fan-out; unset or invalid means no limit.
       def env_worker_timeout_sec
         s = ENV["POLYRUN_WORKER_TIMEOUT_SEC"].to_s.strip
@@ -97,12 +137,7 @@ module Polyrun
       # {Partition::Plan#default_weight} semantics: mean of known timing costs for missing paths.
       def queue_weight_for(path, costs, default_weight = nil, granularity: :file)
         g = Polyrun::Partition::TimingKeys.normalize_granularity(granularity)
-        key =
-          if g == :example
-            Polyrun::Partition::TimingKeys.normalize_locator(path.to_s, Dir.pwd, :example)
-          else
-            File.expand_path(path.to_s, Dir.pwd)
-          end
+        key = Polyrun::Partition::TimingKeys.normalize_locator(path.to_s, Dir.pwd, g)
         return costs[key] if costs.key?(key)
 
         unless default_weight.nil?

data/lib/polyrun/cli/plan_command.rb

@@ -167,35 +167,16 @@ module Polyrun
       end
 
       def plan_load_costs_and_strategy(timing_path, strategy, timing_granularity, strategy_explicit: false)
-        strategy = strategy.to_s
-        if timing_path
-          if strategy_explicit && strategy == "round_robin"
-            return [nil, strategy]
-          end
-
-          costs = Polyrun::Partition::Plan.load_timing_costs(
-            File.expand_path(timing_path.to_s, Dir.pwd),
-            granularity: timing_granularity
-          )
-          if costs.empty?
-            Polyrun::Log.warn "polyrun plan: timing file missing or has no entries: #{timing_path}"
-            return nil
-          end
-          if Polyrun::Partition::Plan.timing_load_strategy?(strategy)
-            return [costs, strategy]
-          end
-          unless strategy_explicit
-            Polyrun::Log.warn "polyrun plan: using cost_binpack (timing data present)" if @verbose
-            return [costs, "cost_binpack"]
-          end
-
-          [nil, strategy]
-        elsif Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.lazy_robin_strategy?(strategy)
-          Polyrun::Log.warn "polyrun plan: --timing or partition.timing_file required for strategy #{strategy}"
-          nil
-        else
-          [nil, strategy]
-        end
+        costs, resolved, err = partition_resolve_costs_and_strategy(
+          timing_path,
+          strategy,
+          timing_granularity,
+          strategy_explicit: strategy_explicit,
+          log_prefix: "polyrun plan"
+        )
+        return nil if err
+
+        [costs, resolved]
       end
     end
   end

data/lib/polyrun/cli/run_queue_command.rb

@@ -43,6 +43,14 @@ module Polyrun
         end.parse!(head)
 
         workers ||= env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS)
+        unless workers.is_a?(Integer) && workers.between?(1, Polyrun::Config::MAX_PARALLEL_WORKERS)
+          Polyrun::Log.warn "polyrun run-queue: --workers must be between 1 and #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
+          return 2
+        end
+        unless batch.is_a?(Integer) && batch >= 1
+          Polyrun::Log.warn "polyrun run-queue: --batch must be >= 1"
+          return 2
+        end
         paths_file ||= pc["paths_file"] || pc[:paths_file]
         unless paths_file
           Polyrun::Log.warn "polyrun run-queue: need --paths-file or partition.paths_file"
@@ -87,7 +95,8 @@ module Polyrun
             result = Polyrun::Queue::WorkerLoop.run(
               store: store, worker_id: wid, batch: batch, cmd: cmd, on_failure: on_failure
             )
-            exit result[:exit_code]
+            # exit! skips parent at_exit hooks (Coverage finish, RSpec autorun) loaded in this process.
+            exit! result[:exit_code]
           end
           pids << {pid: pid, worker_id: wid}
         end

data/lib/polyrun/cli/run_shards_command.rb

@@ -40,11 +40,8 @@ module Polyrun
       end
 
       # Same as parallel-rspec but runs +bundle exec rails test+ or +bundle exec ruby -I test+ after +--+.
+      # Does not run +start+ prepare/database bootstrap (use +polyrun start+ or bare +polyrun+ for that).
       def cmd_parallel_minitest(argv, config_path)
-        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
-        code = start_bootstrap!(cfg, argv, config_path)
-        return code if code != 0
-
         sep = argv.index("--")
         combined =
           if sep
@@ -60,11 +57,8 @@ module Polyrun
 
       # Same as parallel-rspec but runs +bundle exec polyrun quick+ after +--+ (one Quick process per shard).
       # Run from the app root with +bundle exec+ so workers resolve the same gem as the parent (same concern as +bundle exec rspec+).
+      # Does not run +start+ prepare/database bootstrap (use +polyrun start+ or bare +polyrun+ for that).
       def cmd_parallel_quick(argv, config_path)
-        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
-        code = start_bootstrap!(cfg, argv, config_path)
-        return code if code != 0
-
         sep = argv.index("--")
         combined =
           if sep

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -24,49 +24,55 @@ module Polyrun
 
         pids = []
         Polyrun::WorkerOutput.prepare_log_dir! if Polyrun::WorkerOutput.routing_enabled?
-        workers.times do |shard|
-          paths = plan.shard(shard)
-          if paths.empty?
-            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
-            next
-          end
+        begin
+          workers.times do |shard|
+            paths = plan.shard(shard)
+            if paths.empty?
+              Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
+              next
+            end
 
-          env_shard = ENV.to_h.merge(
-            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
-            "POLYRUN_SHARD_INDEX" => shard.to_s,
-            "POLYRUN_SHARD_TOTAL" => workers.to_s
-          )
-          code = hook_cfg.run_phase_if_enabled(:before_shard, env_shard)
-          if code != 0
-            run_shards_terminate_children!(pids)
-            return [pids, code]
-          end
+            env_shard = ENV.to_h.merge(
+              "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+              "POLYRUN_SHARD_INDEX" => shard.to_s,
+              "POLYRUN_SHARD_TOTAL" => workers.to_s
+            )
+            code = hook_cfg.run_phase_if_enabled(:before_shard, env_shard)
+            if code != 0
+              run_shards_terminate_children!(pids)
+              return [pids, code]
+            end
 
-          child_env = shard_child_env(
-            cfg: cfg,
-            workers: workers,
-            shard: shard,
-            matrix_index: mx,
-            matrix_total: mt,
-            failure_fragments: ctx[:merge_failures],
-            spec_quality_fragments: ctx[:merge_spec_quality]
-          )
-          child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
-          child_env = hook_cfg.merge_worker_ruby_env(child_env)
+            child_env = shard_child_env(
+              cfg: cfg,
+              workers: workers,
+              shard: shard,
+              matrix_index: mx,
+              matrix_total: mt,
+              failure_fragments: ctx[:merge_failures],
+              spec_quality_fragments: ctx[:merge_spec_quality]
+            )
+            child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
+            child_env = hook_cfg.merge_worker_ruby_env(child_env)
 
-          ping_path = run_shards_prepare_worker_ping!(ctx, child_env, shard)
+            ping_path = run_shards_prepare_worker_ping!(ctx, child_env, shard)
 
-          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
-          spawned_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          pid = run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
-          pids << {pid: pid, shard: shard, 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)}"
+            Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
+            spawned_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            pid = run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+            pids << {pid: pid, shard: shard, 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]
+        rescue StandardError, ScriptError => e
+          Polyrun::Log.warn "polyrun run-shards: spawn failed (#{e.class}: #{e.message}); stopping #{pids.size} worker(s)"
+          run_shards_terminate_children!(pids)
+          [pids, 1]
         end
-        [pids, nil]
       end
       # rubocop:enable Metrics/AbcSize
 
@@ -85,13 +91,20 @@ module Polyrun
         path
       end
 
+      # Workers start in their own process group so TERM/KILL can reach hook shell grandchildren.
       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))
+          Process.spawn(
+            child_env,
+            "sh",
+            "-c",
+            hook_cfg.build_worker_shell_script(cmd, paths),
+            pgroup: true
+          )
         else
-          Process.spawn(child_env, *cmd, *paths)
+          Process.spawn(child_env, *cmd, *paths, pgroup: true)
         end
       end
     end

data/lib/polyrun/cli/run_shards_parallel_wait.rb

@@ -234,7 +234,7 @@ module Polyrun
       end
 
       def run_shards_force_stop_pid_status(pid)
-        Process.kill(:KILL, pid)
+        run_shards_kill_process_group!(:KILL, pid)
         st = nil
         begin
           Process.wait(pid)
@@ -243,7 +243,7 @@ module Polyrun
           # child already reaped
         end
         st
-      rescue Errno::ESRCH
+      rescue Errno::ESRCH, Errno::EPERM
         begin
           Process.wait(pid)
           $?

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -33,6 +33,9 @@ module Polyrun
         items, paths_source, err = run_shards_resolve_items(o[:paths_file], pc)
         return [err, nil] if err
 
+        err = run_shards_validate_suite_vs_command!(items, cmd)
+        return [err, nil] if err
+
         costs, strategy, err = run_shards_resolve_costs(
           o[:timing_path],
           o[:strategy],

data/lib/polyrun/cli/run_shards_planning.rb

@@ -64,39 +64,26 @@ module Polyrun
           Polyrun::Log.warn "polyrun run-shards: no paths (empty paths file or list)"
           return [nil, nil, 2]
         end
+
         [items, paths_source, nil]
       end
 
+      def run_shards_validate_suite_vs_command!(items, cmd)
+        msg = Polyrun::Partition::Suite.command_mismatch_message(items, cmd)
+        return nil unless msg
+
+        Polyrun::Log.warn "polyrun run-shards: #{msg}"
+        2
+      end
+
       def run_shards_resolve_costs(timing_path, strategy, timing_granularity, strategy_explicit: false)
-        strategy = strategy.to_s
-        if timing_path
-          if strategy_explicit && strategy == "round_robin"
-            return [nil, strategy, nil]
-          end
-
-          costs = Polyrun::Partition::Plan.load_timing_costs(
-            File.expand_path(timing_path.to_s, Dir.pwd),
-            granularity: timing_granularity
-          )
-          if costs.empty?
-            Polyrun::Log.warn "polyrun run-shards: timing file missing or empty: #{timing_path}"
-            return [nil, nil, 2]
-          end
-          if Polyrun::Partition::Plan.timing_load_strategy?(strategy)
-            return [costs, strategy, nil]
-          end
-          unless strategy_explicit
-            Polyrun::Log.warn "polyrun run-shards: using cost_binpack (timing data present)" if @verbose
-            return [costs, "cost_binpack", nil]
-          end
-
-          [nil, strategy, nil]
-        elsif Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.lazy_robin_strategy?(strategy)
-          Polyrun::Log.warn "polyrun run-shards: --timing or partition.timing_file required for strategy #{strategy}"
-          [nil, nil, 2]
-        else
-          [nil, strategy, nil]
-        end
+        partition_resolve_costs_and_strategy(
+          timing_path,
+          strategy,
+          timing_granularity,
+          strategy_explicit: strategy_explicit,
+          log_prefix: "polyrun run-shards"
+        )
       end
 
       def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity, stable_assignment = nil, shard_weights: nil)

data/lib/polyrun/cli/run_shards_run.rb

@@ -127,7 +127,7 @@ module Polyrun
         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."
+        Polyrun::Log.warn "polyrun run-shards: RSpec summary counts apply to individual shards."
       end
 
       def run_shards_merge_or_hint_coverage(ctx)