polyrun 1.5.0 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d4fc5867eb97f45848d6da2b7ac8d0c3906de5cd0df849f02042aaaee1e9bbf
-  data.tar.gz: a10e216d02b76c722627ab5d0c73e5fe061c118d14f356bdc620655a7e83454a
+  metadata.gz: 756cf8e1b8e2176c4097520752dfdd4b856d03b134a999462641f90a9f217e71
+  data.tar.gz: 284e536d886b4bfc913415b0e3301a31ca98ef3446da1b24163bcc6af485e642
 SHA512:
-  metadata.gz: fd37e0e3c6f3afccb8da9dba32b0b836d6b0ddf25181b0bbc2b3d20be561d93518af54ffb929cb62511259a788ad080f9f7080252231d3554aee5ab056c3c841
-  data.tar.gz: 92cb1e5ded19005ccca5975754525857ae5f1b9561947b9a6d1b736e62c098a61e377e3465dba1add9d265277f44672911be48e27097b9c3813ef188341f3a94
+  metadata.gz: 445f64e0e62be50ab6c63026f27ad8f5f093521bbeed4a05b0ce7adc6a13bcb0496f1489d8243b403f859826e599194c3399a761a9210cbbf5d8027f3fdba52e
+  data.tar.gz: 554a292c2c7ac40e3df11d886ca7a71c10b81f1fa144af00c5c1d20b950ff6d999306be1e3fa75a9982450b2d202bc2bee34d5201ab39dbb386b1b73b42f1403

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+## 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`.
+- Add `Polyrun::RSpec.install_spec_quality!`, `Polyrun::Minitest.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`.
+
+## 2.0.0 (2026-07-03)
+
+- Add `polyrun run-queue` to init a file-backed queue and run N workers that claim batches until drained; `--on-failure exit|requeue` reclaims open leases when a worker exits before ack.
+- Add `polyrun queue reclaim` with `--older-than DURATION` (`10m`, `1h`, …) and optional `--worker ID`; add `Queue::FileStore#reclaim!` and `#reclaim_lease!`.
+- Add partition imbalance and dominant-file reports after `plan` and `run-shards` (`Partition::Reports`); warn on stale or missing timing coverage before cost-based partition (`Partition::TimingDiagnostics`).
+- Add partition strategies `lazy_robin` (sorted round-robin with timing diagnostics), `preserve_order_round_robin` (paths-file order), `stable_cost_binpack` (stable assignment with LPT fallback), and `weighted_hrw` (rendezvous with `shard_weights`).
+- Add `partition.stable_assignment_file` and `partition.shard_weights` for stable binpack and weighted HRW; wire into `plan` and `run-shards`.
+- Add `Polyrun::Timing::Stats` for rich timing entries (`last_seconds`, `mean`, `p95`, `runs`, `failures`, `timeouts`); `merge-timing` merges via `Stats.merge_entries` and emits `Timing::VarianceReport` warnings.
+- Add `POLYRUN_HRW_FAST_SCORE` for faster deterministic HRW scoring.
+- Auto-select `cost_binpack` when `partition.timing_file` or `--timing` is set and strategy is not explicit; load timing for `lazy_robin` and diagnostics even when strategy stays round-robin.
+- Fix `paths_build` glob stages to match against the remaining pool (`File.fnmatch?`) instead of re-globbing the cwd.
+- Warn when a database URL has no database segment (shard suffix skipped); name `shard_index` in `CloneShards` errors.
+- Refactor LPT forced-item handling into a single pass before free-item balance.
+- Add Makefile, Prayfile, and root `polyrun.yml`; run repo specs via polyrun in CI.
+- BREAKING: `partition.timing_file` without an explicit `strategy` now implies `cost_binpack` instead of `round_robin`.
+- BREAKING: `merge-timing` output entries are objects with timing stats, not bare scalar seconds; tools that read merged JSON must accept objects or use `Stats.binpack_weight`.
+- BREAKING: `paths_build` glob stages filter the staged pool only; membership and order can differ from prior re-glob behavior.
+
 ## 1.5.0 (2026-05-04)
 
 - 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.

data/README.md

@@ -23,7 +23,7 @@ Capybara and Playwright stay in your application; Polyrun does not replace brows
 2. Add a `polyrun.yml` beside the app, or pass `-c` to point at one. Configure `partition` (paths, shard index and total, strategy), and optionally `databases` (Postgres template and `shard_db_pattern`), `prepare`, and `coverage`. If you use `partition.paths_build`, Polyrun can write `partition.paths_file` (for example `spec/spec_paths.txt`) from globs and ordered stages—substring priorities for integration specs, or a regex stage for “Rails-heavy files first”—without a per-project Ruby script. That step runs before `plan` and `run-shards`. Use `bin/polyrun build-paths` to refresh the paths file only.
 3. Run prepare once before fan-out—for example `script/ci_prepare` for Vite or webpack builds, and `Polyrun::Prepare::Assets` digest markers. See `examples/TESTING_REQUIREMENTS.md`.
 4. Run workers with `bin/polyrun run-shards --workers N -- bundle exec rspec`: N separate OS processes, each running RSpec with its own file list from `partition.paths_file`, or `spec/spec_paths.txt`, or else `spec/**/*_spec.rb`. Stderr shows where paths came from; after a successful multi-worker run it reminds you to run merge-coverage unless you use `parallel-rspec` or `run-shards --merge-coverage`.
-5. Merge artifacts with `bin/polyrun merge-coverage` on `coverage/polyrun-fragment-*.json` (one fragment per `POLYRUN_SHARD_INDEX` when coverage is on), or use `bin/polyrun parallel-rspec` or `run-shards --merge-coverage` so Polyrun runs merge for you. Optional: `merge-timing`, `report-timing`, `report-junit`.
+5. Merge artifacts with `bin/polyrun merge-coverage` on `coverage/polyrun-fragment-*.json` (one fragment per `POLYRUN_SHARD_INDEX` when coverage is on), or use `bin/polyrun parallel-rspec` or `run-shards --merge-coverage` so Polyrun runs merge for you. Optional: `merge-timing`, `report-timing`, `report-junit`, `merge-spec-quality`, `report-spec-quality` (experimental per-example spec quality; see [docs/SPEC_QUALITY.md](docs/SPEC_QUALITY.md)).
 
 ### Hooks (`hooks:` in `polyrun.yml`)
 
@@ -189,7 +189,7 @@ bin/polyrun quick spec/polyrun_quick/smoke.rb
 
 Shard index and total in CI (`Polyrun::Env::Ci`): when set, `POLYRUN_SHARD_INDEX` and `POLYRUN_SHARD_TOTAL` take precedence. When `CI` is truthy, `CI_NODE_INDEX` / `CI_NODE_TOTAL` and other parallel-job environment variables are read if present. If your runner does not export those, set `POLYRUN_SHARD_*` from the job matrix.
 
-File queue (`polyrun queue …`): batches live on disk under a lock file; paths move from `pending` to `leases` on claim and to `done` on ack. There is no lease TTL: if a worker dies after claiming, paths remain in `leases` until you recover them (manually or with a future reclaim command).
+File queue (`polyrun queue …`): batches live on disk under a lock file; paths move from `pending` to `leases` on claim and to `done` on ack. Stale leases can be returned to `pending` with `polyrun queue reclaim --older-than 10m` (or `--worker ID`). Use `polyrun queue status --json` for lease ages. `polyrun run-queue` reclaims a worker's open lease when that worker exits before ack.
 
 ## Examples
 

data/docs/SETUP_PROFILE.md

@@ -45,6 +45,8 @@ 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 |
 
+`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).
 
 ## 6. Coverage and CI reports

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,20 +13,20 @@ 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.
-          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).
+          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:
             version              print version
@@ -34,21 +34,24 @@ module Polyrun
             prepare              run prepare recipe: default | assets (optional prepare.command overrides bin/rails assets:precompile) | shell (prepare.command required)
             merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console)
             merge-failures       merge per-shard failure JSONL fragments or RSpec JSON files (jsonl/json)
-            run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage / --merge-failures
+            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 --)
             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]
             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); M workers share one dir; no duplicate paths across claims
-            quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
+            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!)
             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)
             report-timing        print slow-file summary from merged timing JSON
             merge-timing         merge polyrun_timing_*.json shards
-            config               print effective config by dotted path (see Polyrun::Config::Effective; same tree as YAML plus merged prepare.env, resolved partition shard fields, workers)
+            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 (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/helpers.rb

@@ -119,6 +119,22 @@ module Polyrun
       def resolve_partition_timing_granularity(pc, cli_val)
         Polyrun::Config::Resolver.resolve_partition_timing_granularity(pc, cli_val)
       end
+
+      def load_stable_assignment(pc)
+        path = pc["stable_assignment_file"] || pc[:stable_assignment_file]
+        return nil unless path
+
+        abs = File.expand_path(path.to_s, Dir.pwd)
+        return nil unless File.file?(abs)
+
+        data = JSON.parse(File.read(abs))
+        return data if data.is_a?(Hash)
+
+        nil
+      rescue JSON::ParserError
+        Polyrun::Log.warn "polyrun: invalid stable_assignment_file JSON: #{abs}"
+        nil
+      end
     end
   end
 end

data/lib/polyrun/cli/init_command.rb

@@ -1,4 +1,5 @@
 require "optparse"
+require "fileutils"
 
 module Polyrun
   class CLI
@@ -7,6 +8,7 @@ module Polyrun
         "gem" => "minimal_gem.polyrun.yml",
         "rails" => "rails_prepare.polyrun.yml",
         "ci-matrix" => "ci_matrix.polyrun.yml",
+        "spec-quality" => "polyrun_spec_quality.yml",
         "doc" => "POLYRUN.md"
       }.freeze
 
@@ -34,6 +36,7 @@ module Polyrun
         path = File.expand_path(dest)
         return init_refuses_overwrite(path) if File.file?(path) && !force
 
+        FileUtils.mkdir_p(File.dirname(path))
         File.write(path, body)
         Polyrun::Log.warn "polyrun init: wrote #{path}"
         0
@@ -92,7 +95,11 @@ module Polyrun
       end
 
       def default_init_output(profile)
-        (profile == "doc") ? "POLYRUN.md" : "polyrun.yml"
+        case profile
+        when "doc" then "POLYRUN.md"
+        when "spec-quality" then "config/polyrun_spec_quality.yml"
+        else "polyrun.yml"
+        end
       end
     end
   end

data/lib/polyrun/cli/partition_diagnostics.rb

@@ -0,0 +1,22 @@
+module Polyrun
+  class CLI
+    # Shared stderr diagnostics after {Partition::Plan} is built.
+    module PartitionDiagnostics
+      private
+
+      def partition_emit_diagnostics!(plan:, items:, costs:, timing_path:, granularity: :file)
+        return unless timing_path && costs && !costs.empty?
+
+        analysis = Polyrun::Partition::TimingDiagnostics.analyze(
+          items: items,
+          costs: costs,
+          timing_path: timing_path,
+          root: plan.root,
+          granularity: granularity
+        )
+        Polyrun::Partition::TimingDiagnostics.emit_warnings!(analysis)
+        Polyrun::Partition::Reports.emit_all!(plan)
+      end
+    end
+  end
+end

data/lib/polyrun/cli/plan_command.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Polyrun/FileLength -- plan argv + partition emit
 require "json"
 require "optparse"
 
@@ -38,8 +39,9 @@ module Polyrun
 
         items, costs, strategy = bundle
         constraints = load_partition_constraints(pc, ctx[:constraints_path])
+        stable = load_stable_assignment(pc)
 
-        manifest = plan_command_build_manifest(
+        manifest, plan = plan_command_build_manifest(
           items: items,
           total: ctx[:total],
           strategy: strategy,
@@ -47,7 +49,16 @@ module Polyrun
           costs: costs,
           constraints: constraints,
           shard: ctx[:shard],
-          timing_granularity: ctx[:timing_granularity]
+          timing_granularity: ctx[:timing_granularity],
+          stable_assignment: stable,
+          shard_weights: pc["shard_weights"] || pc[:shard_weights]
+        )
+        partition_emit_diagnostics!(
+          plan: plan,
+          items: items,
+          costs: costs,
+          timing_path: timing_path,
+          granularity: ctx[:timing_granularity]
         )
         [manifest, 0]
       end
@@ -56,7 +67,12 @@ module Polyrun
         items = plan_plan_items(paths_file, argv)
         return nil if items.nil?
 
-        loaded = plan_load_costs_and_strategy(timing_path, ctx[:strategy], ctx[:timing_granularity])
+        loaded = plan_load_costs_and_strategy(
+          timing_path,
+          ctx[:strategy],
+          ctx[:timing_granularity],
+          strategy_explicit: ctx[:strategy_explicit]
+        )
         return nil if loaded.nil?
 
         costs, strategy = loaded
@@ -68,6 +84,7 @@ module Polyrun
           shard: resolve_shard_index(pc),
           total: resolve_shard_total(pc),
           strategy: (pc["strategy"] || pc[:strategy] || "round_robin").to_s,
+          strategy_explicit: !!(pc["strategy"] || pc[:strategy]),
           seed: pc["seed"] || pc[:seed],
           paths_file: nil,
           timing_path: nil,
@@ -80,10 +97,13 @@ module Polyrun
       def plan_command_register_partition_options!(opts, ctx)
         opts.on("--shard INDEX", Integer) { |v| ctx[:shard] = v }
         opts.on("--total N", Integer) { |v| ctx[:total] = v }
-        opts.on("--strategy NAME", String) { |v| ctx[:strategy] = v }
+        opts.on("--strategy NAME", String) do |v|
+          ctx[:strategy] = v
+          ctx[:strategy_explicit] = true
+        end
         opts.on("--seed VAL") { |v| ctx[:seed] = v }
         opts.on("--constraints PATH", "YAML: pin / serial_glob (see spec_queue.md)") { |v| ctx[:constraints_path] = v }
-        opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
+        opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is explicit or timing-aware") do |v|
           ctx[:timing_path] = v
         end
         opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
@@ -104,7 +124,7 @@ module Polyrun
         end.parse!(argv)
       end
 
-      def plan_command_build_manifest(items:, total:, strategy:, seed:, costs:, constraints:, shard:, timing_granularity: :file)
+      def plan_command_build_manifest(items:, total:, strategy:, seed:, costs:, constraints:, shard:, timing_granularity: :file, stable_assignment: nil, shard_weights: nil)
         plan = Polyrun::Debug.time("Partition::Plan.new (plan command)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -114,7 +134,9 @@ module Polyrun
             costs: costs,
             constraints: constraints,
             root: Dir.pwd,
-            timing_granularity: timing_granularity
+            timing_granularity: timing_granularity,
+            stable_assignment: stable_assignment,
+            shard_weights: shard_weights
           )
         end
         Polyrun::Debug.log_kv(
@@ -124,16 +146,13 @@ module Polyrun
           strategy: strategy,
           path_count: items.size
         )
-        plan.manifest(shard)
+        [plan.manifest(shard), plan]
       end
 
-      def plan_resolve_timing_path(pc, timing_path, strategy)
+      def plan_resolve_timing_path(pc, timing_path, _strategy = nil)
         return timing_path if timing_path
 
-        tf = pc["timing_file"] || pc[:timing_file]
-        return tf if tf && (Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy))
-
-        nil
+        pc["timing_file"] || pc[:timing_file]
       end
 
       def plan_plan_items(paths_file, argv)
@@ -147,8 +166,13 @@ module Polyrun
         end
       end
 
-      def plan_load_costs_and_strategy(timing_path, strategy, timing_granularity)
+      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
@@ -157,12 +181,16 @@ module Polyrun
             Polyrun::Log.warn "polyrun plan: timing file missing or has no entries: #{timing_path}"
             return nil
           end
-          unless Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy)
+          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
-            strategy = "cost_binpack"
+            return [costs, "cost_binpack"]
           end
-          [costs, strategy]
-        elsif Polyrun::Partition::Plan.cost_strategy?(strategy)
+
+          [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
@@ -172,3 +200,4 @@ module Polyrun
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/cli/queue_command.rb

@@ -34,8 +34,10 @@ module Polyrun
           queue_cmd_ack(argv, dir, lease_id, worker)
         when "status"
           queue_cmd_status(argv, dir)
+        when "reclaim"
+          queue_cmd_reclaim(argv, dir)
         else
-          Polyrun::Log.warn "usage: polyrun queue {init|claim|ack|status} [options]"
+          Polyrun::Log.warn "usage: polyrun queue {init|claim|ack|status|reclaim} [options]"
           2
         end
       end
@@ -126,13 +128,34 @@ module Polyrun
       end
 
       def queue_cmd_status(argv, dir)
+        json_detail = false
         OptionParser.new do |opts|
+          opts.banner = "usage: polyrun queue status [--dir DIR] [--json]"
           opts.on("--dir PATH") { |v| dir = v }
+          opts.on("--json", "Include lease details") { json_detail = true }
         end.parse!(argv)
-        s = Polyrun::Queue::FileStore.new(dir).status
+        s = Polyrun::Queue::FileStore.new(dir).status(detailed: json_detail)
         Polyrun::Log.puts JSON.generate(s)
         0
       end
+
+      def queue_cmd_reclaim(argv, dir)
+        older_than = nil
+        worker = nil
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun queue reclaim [--dir DIR] [--older-than DURATION] [--worker ID]"
+          opts.on("--dir PATH") { |v| dir = v }
+          opts.on("--older-than DUR", "e.g. 10m, 1h, 600s") { |v| older_than = Polyrun::Queue::Duration.parse_seconds(v) }
+          opts.on("--worker ID") { |v| worker = v }
+        end.parse!(argv)
+        unless older_than || worker
+          Polyrun::Log.warn "queue reclaim: need --older-than or --worker"
+          return 2
+        end
+        n = Polyrun::Queue::FileStore.new(dir).reclaim!(older_than: older_than, worker_id: worker)
+        Polyrun::Log.puts JSON.generate({"reclaimed_paths" => n})
+        0
+      end
     end
   end
 end

data/lib/polyrun/cli/run_queue_command.rb

@@ -0,0 +1,145 @@
+require "json"
+require "optparse"
+require "shellwords"
+
+require_relative "../queue/duration"
+
+module Polyrun
+  class CLI
+    module RunQueueCommand
+      private
+
+      # rubocop:disable Metrics/AbcSize -- queue worker argv + spawn loop
+      def cmd_run_queue(argv, config_path)
+        dir = ".polyrun-queue"
+        batch = 5
+        on_failure = "exit"
+        paths_file = nil
+        workers = nil
+
+        sep = argv.index("--")
+        unless sep
+          Polyrun::Log.warn "polyrun run-queue: need -- before the command"
+          return 2
+        end
+
+        head = argv[0...sep]
+        cmd = argv[(sep + 1)..].map(&:to_s)
+        return 2 if cmd.empty?
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        ctx = plan_command_initial_context(pc)
+
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun run-queue [--workers N] [--batch N] [--dir DIR] [--on-failure exit|requeue] [partition options] -- <command>"
+          opts.on("--workers N", Integer) { |v| workers = v }
+          opts.on("--batch N", Integer) { |v| batch = v }
+          opts.on("--dir PATH") { |v| dir = v }
+          opts.on("--paths-file PATH", String) { |v| paths_file = v }
+          opts.on("--on-failure MODE", "exit (default) or requeue") { |v| on_failure = v }
+          plan_command_register_partition_options!(opts, ctx)
+        end.parse!(head)
+
+        workers ||= env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS)
+        paths_file ||= pc["paths_file"] || pc[:paths_file]
+        unless paths_file
+          Polyrun::Log.warn "polyrun run-queue: need --paths-file or partition.paths_file"
+          return 2
+        end
+
+        code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
+        return code if code != 0
+
+        store = Polyrun::Queue::FileStore.new(dir)
+        if File.file?(File.join(File.expand_path(dir), "queue.json"))
+          Polyrun::Log.warn "polyrun run-queue: queue already exists at #{dir}; remove it or use --dir"
+          return 2
+        end
+
+        ordered, code = queue_partition_manifest_and_ordered_paths(cfg, pc, ctx, paths_file)
+        return code if code != 0
+
+        store.init!(ordered)
+        Polyrun::Log.warn "polyrun run-queue: #{ordered.size} path(s), #{workers} worker(s), batch=#{batch}" if @verbose
+
+        run_t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        pids = run_queue_spawn_workers(store: store, workers: workers, batch: batch, cmd: cmd, on_failure: on_failure)
+        results = run_queue_wait_workers(pids, store: store, on_failure: on_failure)
+        wall = Process.clock_gettime(Process::CLOCK_MONOTONIC) - run_t0
+
+        stat = store.status(detailed: true)
+        Polyrun::Log.warn format(
+          "polyrun run-queue: done pending=%d done=%d leases=%d wall=%.1fs batches_ok=%d batches_fail=%d",
+          stat["pending"], stat["done"], stat["leases"], wall, results[:ok], results[:fail]
+        )
+
+        results[:fail].positive? ? 1 : 0
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def run_queue_spawn_workers(store:, workers:, batch:, cmd:, on_failure:)
+        pids = []
+        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)
+          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
+        pid_to_worker = pids.each_with_object({}) { |entry, h| h[entry[:pid]] = entry[:worker_id] }
+        while pid_to_worker.any?
+          pid, st = Process.wait2(-1)
+          worker_id = pid_to_worker.delete(pid)
+          next unless worker_id
+
+          if st.success?
+            ok += 1
+          else
+            fail += 1
+            reclaimed = store.reclaim!(worker_id: worker_id)
+            Polyrun::Log.warn "polyrun run-queue: reclaimed #{reclaimed} path(s) from #{worker_id}" if reclaimed.positive?
+          end
+        end
+        {ok: ok, fail: fail}
+      end
+    end
+  end
+end

data/lib/polyrun/cli/run_shards_command.rb

@@ -3,6 +3,7 @@ require "rbconfig"
 
 require_relative "start_bootstrap"
 require_relative "failure_commands"
+require_relative "spec_quality_commands"
 require_relative "run_shards_run"
 
 module Polyrun
@@ -10,6 +11,7 @@ module Polyrun
     module RunShardsCommand
       include StartBootstrap
       include FailureCommands
+      include SpecQualityCommands
       include RunShardsRun
 
       private
@@ -116,11 +118,13 @@ module Polyrun
       # ENV for a worker process: POLYRUN_SHARD_* plus per-shard database URLs from polyrun.yml or DATABASE_URL.
       # When +matrix_total+ > 1 with multiple local workers, sets +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+
       # so {Coverage::Collector} can name fragments uniquely across CI matrix jobs (NxM sharding).
-      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil, failure_fragments: false)
+      # rubocop:disable Metrics/AbcSize -- shard ENV: matrix, DB URLs, fragment flags
+      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil, failure_fragments: false, spec_quality_fragments: false)
         child_env = ENV.to_h.merge(
           Polyrun::Database::Shard.env_map(shard_index: shard, shard_total: workers)
         )
         child_env["POLYRUN_FAILURE_FRAGMENTS"] = "1" if failure_fragments
+        child_env["POLYRUN_SPEC_QUALITY_FRAGMENTS"] = "1" if spec_quality_fragments
         mt = matrix_total.nil? ? 0 : Integer(matrix_total)
         if mt > 1
           if matrix_index.nil?
@@ -138,6 +142,7 @@ module Polyrun
         end
         child_env
       end
+      # rubocop:enable Metrics/AbcSize
 
       def cmd_build_paths(config_path)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])