polyrun 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0c4afee7136f1cdf3ffe319d55c08457323119102a0a4d01478b02df91ce31
-  data.tar.gz: d468805765ee230bed530fdce182f189c0521e3dff7516be5c75bc620c362fc8
+  metadata.gz: 65a84fc362b402e23a550b5ea4f9980a5f6fc896fb5d1c445c3c8d2b22849604
+  data.tar.gz: 55c8baa0261b1e012c5b82592c82ae68409481eb7bee01503a0408d7b837fafe
 SHA512:
-  metadata.gz: 98e04c5388e51da737bb73407497830d82bf61daabdfd77e9024fd2d973663dfed934c87691c6f2e864d7642e457a1eaaff27e3cf3f79bfa102a92ec9a0034aa
-  data.tar.gz: b6c407039df97914ed8e07a04bdb0dc4c8e044d9b0ffd3802e44e600a6c4002fe22b8673266263c5981bb4bde90246c992defb589eb3b785952b0c56f67c263e
+  metadata.gz: 50b5673497a1454363faf29781f9c5fc6f231cb5e8f85b570da61e036af3cb78450e2b6dc4854db1fe99528c292fece8f022c4e6cf69638bc8c09881fdb63a18
+  data.tar.gz: b10cf9ec6d80d0aeecfda0965ec6d7473d4c69a70a520bb3fb5b911679a0ba00d28be163f90458b7d4c3f5a62aa1de94739fb70811a5e82fe136651ca2c07c14

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# CHANGELOG
+
+## 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 `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).
+- Fix noisy `IOError` / broken-pipe behavior when interrupting long-running prepare / Rails subprocesses that previously used `Open3.capture3`.
+
+## 1.0.0 (2026-04-14)
+
+- Initial stable release of Polyrun: parallel tests, SimpleCov-compatible coverage formatters, fixtures/snapshots, assets and DB provisioning with zero runtime gem dependencies.
+- Add `polyrun` CLI with `plan`, `run-shards`, partition/load balancing, coverage merge and reporting, database helpers, queue helpers, and the Quick runner.
+- Add coverage Rake tasks and YAML configuration for merged / Cobertura-style output.
+- Add database command flows using `db:prepare` (replacing earlier `db:migrate`-only paths) for provisioning-style runs.
+- Implement graceful shutdown for worker processes in `run_shards` when the parent is interrupted.
+- Expand Quick runner defaults and parallel shard database creation.
+- Add examples tree, specs for merge and queue behavior, and docs for cwd-relative configuration.
+- Add RSpec suite, RuboCop (including a FileLength cop), YAML templates, and a `bin/release` script.
+- Add RBS signatures under `sig/` and validate them in CI; expand documentation and specs.

data/README.md

@@ -8,7 +8,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.
+- 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.
 - 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_*`.
@@ -32,6 +32,8 @@ If the current directory already has `polyrun.yml` or `config/polyrun.yml`, you
 ```bash
 bin/polyrun version
 bin/polyrun build-paths   # write spec/spec_paths.txt from partition.paths_build (uses polyrun.yml in cwd)
+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 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
@@ -41,6 +43,12 @@ bin/polyrun init --profile gem -o polyrun.yml   # starter YAML; see docs/SETUP_P
 bin/polyrun quick   # Polyrun::Quick examples under spec/polyrun_quick/ or test/polyrun_quick/
 ```
 
+### Matrix shards and timing
+
+- `ci-shard-run` — Pass the command as separate words after `--` (e.g. `ci-shard-run -- bundle exec rspec`). One combined string with spaces is split via `Shellwords`, not a full shell; shell-only quoting does not apply.
+- Timing JSON — Run `plan`, `queue init`, and `merge-timing` from the same repository root (cwd) you use when producing `polyrun_timing.json` so path keys normalize consistently. `Polyrun::Partition::Plan.load_timing_costs` and `TimingKeys.load_costs_json_file` accept `root:` to align keys to a fixed directory.
+- Per-example timing (`--timing-granularity example`) — Experimental. Cost maps and plan items scale with example count, not file count; expect larger memory use and slower planning than file mode on big suites.
+
 ### Adopting Polyrun (setup profile and scaffolds)
 
 - [docs/SETUP_PROFILE.md](docs/SETUP_PROFILE.md) — Checklist for project type (gem, Rails, Appraisal), parallelism target (one CI job with N workers, matrix shards, or a single non-matrix runner), database layout, prepare, spec order, coverage, and CI model A (single runner with `parallel-rspec`) versus model B (matrix plus a merge-coverage job). Treat `polyrun.yml` as the contract; bin scripts and `database.yml` are adapters.
@@ -131,7 +139,19 @@ See [`examples/README.md`](examples/README.md) for Rails apps (Capybara, Playwri
 
 You can replace SimpleCov and simplecov plugins, parallel_tests, and rspec_junit_formatter with Polyrun for those roles. Use `merge-timing`, `report-timing`, and `Data::FactoryCounts` (optionally with `Data::FactoryInstrumentation`) for slow-file and factory metrics. YAML fixture batches and bulk inserts can use `Data::Fixtures` and `ParallelProvisioning` for shard-aware seeding; wire your own `truncate` and `load_seed` in hooks.
 
----
+## License
+
+Released under the [MIT License](LICENSE). Copyright (c) 2026 Andrei Makarov.
+
+## Contributing
+
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, RuboCop, RBS, optional Trunk, and PR conventions. Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Security
+
+Do not open public issues for security vulnerabilities. See [SECURITY.md](SECURITY.md) for how to report them.
+
+## Sponsors
 
 Sponsored by [Kisko Labs](https://www.kiskolabs.com).
 

data/docs/SETUP_PROFILE.md

@@ -81,7 +81,7 @@ Model A — one job, N worker processes
 Model B — matrix of jobs (one shard per job)
 
 - Each job sets `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL` (and DB URLs per shard if needed).
-- Run `polyrun build-paths`, `polyrun plan`, then `bundle exec rspec` (or `bin/rspec_ci_shard`) for that shard only.
+- Run `polyrun ci-shard-run -- bundle exec rspec` (or `ci-shard-rspec`), or `ci-shard-run -- bundle exec polyrun quick` / other runners; or the same steps manually (`bin/rspec_ci_shard` wrappers).
 - Upload `coverage/polyrun-fragment-*.json` (or named per shard).
 - A final `merge-coverage` job downloads artifacts and merges.
 

data/lib/polyrun/cli/ci_shard_run_command.rb

@@ -0,0 +1,65 @@
+require "shellwords"
+
+module Polyrun
+  class CLI
+    # One CI matrix job = one global shard (POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL), not +run-shards+
+    # workers on a single host. Runs +build-paths+, +plan+ for that shard, then +exec+ of a user command
+    # with that shard's paths appended (same argv pattern as +run-shards+ after +--+).
+    #
+    # After +--+, prefer **multiple argv tokens** (+bundle+, +exec+, +rspec+, …). A single token that
+    # contains spaces is split with +Shellwords+ (not a full shell); exotic quoting differs from +sh -c+.
+    module CiShardRunCommand
+      private
+
+      # @return [Array(Array<String>, Integer)] [paths, 0] on success, or [nil, exit_code] on failure
+      def ci_shard_planned_paths!(plan_argv, config_path, command_label:)
+        manifest, code = plan_command_compute_manifest(plan_argv, config_path)
+        return [nil, code] if code != 0
+
+        paths = manifest["paths"] || []
+        if paths.empty?
+          Polyrun::Log.warn "polyrun #{command_label}: no paths for this shard (check shard/total and paths list)"
+          return [nil, 2]
+        end
+
+        [paths, 0]
+      end
+
+      # Runner-agnostic matrix shard: +polyrun ci-shard-run [plan options] -- <command> [args...]+
+      # Paths for this shard are appended after the command (like +run-shards+).
+      def cmd_ci_shard_run(argv, config_path)
+        sep = argv.index("--")
+        unless sep
+          Polyrun::Log.warn "polyrun ci-shard-run: need -- before the command (e.g. ci-shard-run -- bundle exec rspec)"
+          return 2
+        end
+
+        plan_argv = argv[0...sep]
+        cmd = argv[(sep + 1)..].map(&:to_s)
+        if cmd.empty?
+          Polyrun::Log.warn "polyrun ci-shard-run: empty command after --"
+          return 2
+        end
+        cmd = Shellwords.split(cmd.first) if cmd.size == 1 && cmd.first.include?(" ")
+
+        paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-run")
+        return code if code != 0
+
+        exec(*cmd, *paths)
+      end
+
+      # Same as +ci-shard-run -- bundle exec rspec+ with an optional second segment for RSpec-only flags:
+      # +polyrun ci-shard-rspec [plan options] [-- [rspec args]]+
+      def cmd_ci_shard_rspec(argv, config_path)
+        sep = argv.index("--")
+        plan_argv = sep ? argv[0...sep] : argv
+        rspec_argv = sep ? argv[(sep + 1)..] : []
+
+        paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-rspec")
+        return code if code != 0
+
+        exec("bundle", "exec", "rspec", *rspec_argv, *paths)
+      end
+    end
+  end
+end

data/lib/polyrun/cli/helpers.rb

@@ -1,5 +1,7 @@
 require "yaml"
 
+require_relative "../partition/timing_keys"
+
 module Polyrun
   class CLI
     module Helpers
@@ -95,9 +97,15 @@ module Polyrun
 
       # +default_weight+ should be precomputed when sorting many paths (e.g. +queue init+), matching
       # {Partition::Plan#default_weight} semantics: mean of known timing costs for missing paths.
-      def queue_weight_for(path, costs, default_weight = nil)
-        abs = File.expand_path(path.to_s, Dir.pwd)
-        return costs[abs] if costs.key?(abs)
+      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
+        return costs[key] if costs.key?(key)
 
         unless default_weight.nil?
           return default_weight
@@ -108,6 +116,14 @@ module Polyrun
 
         vals.sum / vals.size.to_f
       end
+
+      # CLI + polyrun.yml + POLYRUN_TIMING_GRANULARITY; default +:file+.
+      def resolve_partition_timing_granularity(pc, cli_val)
+        raw = cli_val
+        raw ||= pc && (pc["timing_granularity"] || pc[:timing_granularity])
+        raw ||= ENV["POLYRUN_TIMING_GRANULARITY"]
+        Polyrun::Partition::TimingKeys.normalize_granularity(raw || "file")
+      end
     end
   end
 end

data/lib/polyrun/cli/plan_command.rb

@@ -7,6 +7,15 @@ module Polyrun
       private
 
       def cmd_plan(argv, config_path)
+        manifest, code = plan_command_compute_manifest(argv, config_path)
+        return code if code != 0
+
+        Polyrun::Log.puts JSON.generate(manifest)
+        0
+      end
+
+      # @return [Array(Hash, Integer)] manifest hash and exit code (+0+ on success, non-zero on failure)
+      def plan_command_compute_manifest(argv, config_path)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
         pc = cfg.partition
         ctx = plan_command_initial_context(pc)
@@ -14,30 +23,44 @@ module Polyrun
 
         paths_file = ctx[:paths_file] || (pc["paths_file"] || pc[:paths_file])
         code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
-        return code if code != 0
+        return [nil, code] if code != 0
 
+        plan_command_manifest_from_paths(cfg, pc, argv, ctx, paths_file)
+      end
+
+      def plan_command_manifest_from_paths(cfg, pc, argv, ctx, paths_file)
         timing_path = plan_resolve_timing_path(pc, ctx[:timing_path], ctx[:strategy])
+        ctx[:timing_granularity] = resolve_partition_timing_granularity(pc, ctx[:timing_granularity])
         Polyrun::Log.warn "polyrun plan: using #{cfg.path}" if @verbose && cfg.path
 
-        items = plan_plan_items(paths_file, argv)
-        return 2 if items.nil?
-
-        loaded = plan_load_costs_and_strategy(timing_path, ctx[:strategy])
-        return 2 if loaded.nil?
-
-        costs, strategy = loaded
+        bundle = plan_command_items_costs_strategy(paths_file, argv, timing_path, ctx)
+        return [nil, 2] if bundle.nil?
 
+        items, costs, strategy = bundle
         constraints = load_partition_constraints(pc, ctx[:constraints_path])
 
-        plan_command_emit_manifest(
+        manifest = plan_command_build_manifest(
           items: items,
           total: ctx[:total],
           strategy: strategy,
           seed: ctx[:seed],
           costs: costs,
           constraints: constraints,
-          shard: ctx[:shard]
+          shard: ctx[:shard],
+          timing_granularity: ctx[:timing_granularity]
         )
+        [manifest, 0]
+      end
+
+      def plan_command_items_costs_strategy(paths_file, argv, timing_path, ctx)
+        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])
+        return nil if loaded.nil?
+
+        costs, strategy = loaded
+        [items, costs, strategy]
       end
 
       def plan_command_initial_context(pc)
@@ -48,7 +71,8 @@ module Polyrun
           seed: pc["seed"] || pc[:seed],
           paths_file: nil,
           timing_path: nil,
-          constraints_path: nil
+          constraints_path: nil,
+          timing_granularity: nil
         }
       end
 
@@ -64,10 +88,13 @@ module Polyrun
           opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
             ctx[:timing_path] = v
           end
+          opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
+            ctx[:timing_granularity] = v
+          end
         end.parse!(argv)
       end
 
-      def plan_command_emit_manifest(items:, total:, strategy:, seed:, costs:, constraints:, shard:)
+      def plan_command_build_manifest(items:, total:, strategy:, seed:, costs:, constraints:, shard:, timing_granularity: :file)
         plan = Polyrun::Debug.time("Partition::Plan.new (plan command)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -76,7 +103,8 @@ module Polyrun
             seed: seed,
             costs: costs,
             constraints: constraints,
-            root: Dir.pwd
+            root: Dir.pwd,
+            timing_granularity: timing_granularity
           )
         end
         Polyrun::Debug.log_kv(
@@ -86,8 +114,7 @@ module Polyrun
           strategy: strategy,
           path_count: items.size
         )
-        Polyrun::Log.puts JSON.generate(plan.manifest(shard))
-        0
+        plan.manifest(shard)
       end
 
       def plan_resolve_timing_path(pc, timing_path, strategy)
@@ -110,9 +137,12 @@ module Polyrun
         end
       end
 
-      def plan_load_costs_and_strategy(timing_path, strategy)
+      def plan_load_costs_and_strategy(timing_path, strategy, timing_granularity)
         if timing_path
-          costs = Polyrun::Partition::Plan.load_timing_costs(File.expand_path(timing_path.to_s, Dir.pwd))
+          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

data/lib/polyrun/cli/prepare_command.rb

@@ -1,5 +1,4 @@
 require "json"
-require "open3"
 require "optparse"
 
 require_relative "prepare_recipe"

data/lib/polyrun/cli/prepare_recipe.rb

@@ -1,4 +1,4 @@
-require "open3"
+require_relative "../process_stdio"
 
 module Polyrun
   class CLI
@@ -22,8 +22,7 @@ module Polyrun
           return [manifest, nil]
         end
         if custom && !custom.to_s.strip.empty?
-          _out, err, st = Open3.capture3(*([child_env].compact + ["sh", "-c", custom.to_s]), chdir: rails_root)
-          prepare_log_stderr(err)
+          st = prepare_run_shell_inherit_stdio(child_env, custom.to_s, rails_root, silent: !@verbose)
           unless st.success?
             Polyrun::Log.warn "polyrun prepare: assets custom command failed (exit #{st.exitstatus})"
             return [manifest, 1]
@@ -59,8 +58,7 @@ module Polyrun
           return [manifest, nil]
         end
         lines.each_with_index do |line, i|
-          _out, err, st = Open3.capture3(*([child_env].compact + ["sh", "-c", line]), chdir: rails_root)
-          prepare_log_stderr(err)
+          st = prepare_run_shell_inherit_stdio(child_env, line, rails_root, silent: !@verbose)
           unless st.success?
             Polyrun::Log.warn "polyrun prepare: shell step #{i + 1} failed (exit #{st.exitstatus})"
             return [manifest, 1]
@@ -69,8 +67,15 @@ module Polyrun
         [manifest, nil]
       end
 
-      def prepare_log_stderr(err)
-        Polyrun::Log.warn err unless err.to_s.empty?
+      def prepare_run_shell_inherit_stdio(child_env, script, rails_root, silent: false)
+        Polyrun::ProcessStdio.inherit_stdio_spawn_wait(
+          child_env,
+          "sh",
+          "-c",
+          script.to_s,
+          chdir: rails_root,
+          silent: silent
+        )
       end
     end
   end

data/lib/polyrun/cli/queue_command.rb

@@ -11,6 +11,7 @@ module Polyrun
         dir = ".polyrun-queue"
         paths_file = nil
         timing_path = nil
+        timing_granularity = nil
         worker = ENV["USER"] || "worker"
         batch = 5
         lease_id = nil
@@ -19,7 +20,7 @@ module Polyrun
         Polyrun::Debug.log("queue: subcommand=#{sub.inspect}")
         case sub
         when "init"
-          queue_cmd_init(argv, dir, paths_file, timing_path)
+          queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
         when "claim"
           queue_cmd_claim(argv, dir, worker, batch)
         when "ack"
@@ -32,29 +33,38 @@ module Polyrun
         end
       end
 
-      def queue_cmd_init(argv, dir, paths_file, timing_path)
+      def queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun queue init --paths-file P [--timing PATH] [--dir DIR]"
+          opts.banner = "usage: polyrun queue init --paths-file P [--timing PATH] [--timing-granularity VAL] [--dir DIR]"
           opts.on("--dir PATH") { |v| dir = v }
           opts.on("--paths-file PATH") { |v| paths_file = v }
           opts.on("--timing PATH") { |v| timing_path = v }
+          opts.on("--timing-granularity VAL") { |v| timing_granularity = v }
         end.parse!(argv)
         unless paths_file
           Polyrun::Log.warn "queue init: need --paths-file"
           return 2
         end
+        cfg = Polyrun::Config.load(path: ENV["POLYRUN_CONFIG"])
+        g = resolve_partition_timing_granularity(cfg.partition, timing_granularity)
         items = Polyrun::Partition::Paths.read_lines(paths_file)
-        costs = timing_path ? Polyrun::Partition::Plan.load_timing_costs(File.expand_path(timing_path, Dir.pwd)) : nil
-        ordered = queue_init_ordered_items(items, costs)
+        costs =
+          if timing_path
+            Polyrun::Partition::Plan.load_timing_costs(
+              File.expand_path(timing_path, Dir.pwd),
+              granularity: g
+            )
+          end
+        ordered = queue_init_ordered_items(items, costs, g)
         Polyrun::Queue::FileStore.new(dir).init!(ordered)
         Polyrun::Log.puts JSON.generate({"dir" => File.expand_path(dir), "count" => ordered.size})
         0
       end
 
-      def queue_init_ordered_items(items, costs)
+      def queue_init_ordered_items(items, costs, granularity = :file)
         if costs && !costs.empty?
           dw = costs.values.sum / costs.size.to_f
-          items.sort_by { |p| [-queue_weight_for(p, costs, dw), p] }
+          items.sort_by { |p| [-queue_weight_for(p, costs, dw, granularity: granularity), p] }
         else
           items.sort
         end

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -28,13 +28,13 @@ module Polyrun
         items, paths_source, err = run_shards_resolve_items(o[:paths_file])
         return [err, nil] if err
 
-        costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy])
+        costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])
         return [err, nil] if err
 
         run_shards_plan_ready_log(o, strategy, cmd, paths_source, items.size)
 
         constraints = load_partition_constraints(pc, o[:constraints_path])
-        plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints)
+        plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity])
 
         run_shards_debug_shard_sizes(plan, o[:workers])
         Polyrun::Log.warn "polyrun run-shards: #{items.size} paths → #{o[:workers]} workers (#{strategy})" if @verbose

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -9,6 +9,7 @@ module Polyrun
         st = run_shards_plan_options_state(pc)
         run_shards_plan_options_parse!(head, st)
         st[:paths_file] ||= pc["paths_file"] || pc[:paths_file]
+        st[:timing_granularity] = resolve_partition_timing_granularity(pc, st[:timing_granularity])
         st
       end
 
@@ -20,6 +21,7 @@ module Polyrun
           seed: pc["seed"] || pc[:seed],
           timing_path: nil,
           constraints_path: nil,
+          timing_granularity: nil,
           merge_coverage: false,
           merge_output: nil,
           merge_format: nil
@@ -28,18 +30,23 @@ module Polyrun
 
       def run_shards_plan_options_parse!(head, st)
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--] <command> [args...]"
-          opts.on("--workers N", Integer) { |v| st[:workers] = v }
-          opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
-          opts.on("--seed VAL") { |v| st[:seed] = v }
-          opts.on("--paths-file PATH", String) { |v| st[:paths_file] = v }
-          opts.on("--constraints PATH", String) { |v| st[:constraints_path] = v }
-          opts.on("--timing PATH", "merged polyrun_timing.json; implies cost_binpack unless hrw/cost") { |v| st[:timing_path] = v }
-          opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
-          opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
-          opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
+          run_shards_plan_options_register!(opts, st)
         end.parse!(head)
       end
+
+      def run_shards_plan_options_register!(opts, st)
+        opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--] <command> [args...]"
+        opts.on("--workers N", Integer) { |v| st[:workers] = v }
+        opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
+        opts.on("--seed VAL") { |v| st[:seed] = v }
+        opts.on("--paths-file PATH", String) { |v| st[:paths_file] = v }
+        opts.on("--constraints PATH", String) { |v| st[:constraints_path] = v }
+        opts.on("--timing PATH", "merged polyrun_timing.json; implies cost_binpack unless hrw/cost") { |v| st[:timing_path] = v }
+        opts.on("--timing-granularity VAL", "file (default) or example (experimental)") { |v| st[:timing_granularity] = v }
+        opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
+        opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
+        opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
+      end
     end
   end
 end

data/lib/polyrun/cli/run_shards_planning.rb

@@ -70,9 +70,12 @@ module Polyrun
         [items, paths_source, nil]
       end
 
-      def run_shards_resolve_costs(timing_path, strategy)
+      def run_shards_resolve_costs(timing_path, strategy, timing_granularity)
         if timing_path
-          costs = Polyrun::Partition::Plan.load_timing_costs(File.expand_path(timing_path.to_s, Dir.pwd))
+          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]
@@ -90,7 +93,7 @@ module Polyrun
         end
       end
 
-      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints)
+      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity)
         Polyrun::Debug.time("Partition::Plan.new (partition #{items.size} paths → #{workers} shards)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -99,7 +102,8 @@ module Polyrun
             seed: seed,
             costs: costs,
             constraints: constraints,
-            root: Dir.pwd
+            root: Dir.pwd,
+            timing_granularity: timing_granularity
           )
         end
       end

data/lib/polyrun/cli.rb

@@ -12,9 +12,15 @@ require_relative "cli/queue_command"
 require_relative "cli/timing_command"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
+require_relative "cli/ci_shard_run_command"
 
 module Polyrun
   class CLI
+    CI_SHARD_COMMANDS = {
+      "ci-shard-run" => :cmd_ci_shard_run,
+      "ci-shard-rspec" => :cmd_ci_shard_rspec
+    }.freeze
+
     include Helpers
     include PlanCommand
     include PrepareCommand
@@ -27,6 +33,7 @@ module Polyrun
     include TimingCommand
     include InitCommand
     include QuickCommand
+    include CiShardRunCommand
 
     def self.run(argv = ARGV)
       new.run(argv)
@@ -121,6 +128,8 @@ module Polyrun
         cmd_start(argv, config_path)
       when "build-paths"
         cmd_build_paths(config_path)
+      when *CI_SHARD_COMMANDS.keys
+        send(CI_SHARD_COMMANDS.fetch(command), argv, config_path)
       when "init"
         cmd_init(argv, config_path)
       when "queue"
@@ -152,6 +161,7 @@ module Polyrun
         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)
         Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start)
+        Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
 
         commands:
           version              print version
@@ -161,6 +171,8 @@ module Polyrun
           run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage
           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 -- (like run-shards; not multi-worker)
+          ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional -- [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 / claim / ack / status)

data/lib/polyrun/database/provision.rb

@@ -1,5 +1,6 @@
 require "open3"
 require "shellwords"
+require_relative "../process_stdio"
 
 module Polyrun
   module Database
@@ -49,20 +50,24 @@ module Polyrun
       # Multi-DB Rails apps must pass all template URLs in one invocation so each DB uses its own +migrations_paths+.
       # Uses +db:prepare+ (not +db:migrate+ alone) so empty template databases load +schema.rb+ first;
       # apps that squash or archive migrations and keep only incremental files need that path.
+      #
+      # Streams stdout/stderr to the terminal by default. With +silent: true+, redirects child stdio
+      # to +File::NULL+ (no live output; non-interactive).
       def prepare_template!(rails_root:, env:, silent: true)
         exe = File.join(rails_root, "bin", "rails")
         raise Polyrun::Error, "Provision: missing #{exe}" unless File.executable?(exe)
 
         child_env = ENV.to_h.merge(env)
         child_env["RAILS_ENV"] ||= ENV["RAILS_ENV"] || "test"
-        rails_out, err, st = Open3.capture3(child_env, exe, "db:prepare", chdir: rails_root)
-        Polyrun::Log.warn err if !silent && !err.to_s.empty?
+        st, out, err = Polyrun::ProcessStdio.spawn_wait(
+          child_env,
+          exe,
+          "db:prepare",
+          chdir: rails_root,
+          silent: silent
+        )
         unless st.success?
-          msg = +"db:prepare failed"
-          msg << "\n--- stderr ---\n#{err}" unless err.to_s.strip.empty?
-          # Rails often prints the first migration/SQL error on stdout; stderr may only show InFailedSqlTransaction.
-          msg << "\n--- stdout ---\n#{rails_out}" unless rails_out.to_s.strip.empty?
-          raise Polyrun::Error, msg
+          raise Polyrun::Error, Polyrun::ProcessStdio.format_failure_message("db:prepare", st, out, err)
         end
 
         true

data/lib/polyrun/partition/constraints.rb

@@ -1,3 +1,5 @@
+require_relative "timing_keys"
+
 module Polyrun
   module Partition
     # Hard constraints for plan assignment (spec_queue.md): pins, serial globs.
@@ -31,21 +33,30 @@ module Polyrun
       end
 
       # Returns Integer shard index if constrained, or nil if free to place by LPT/HRW.
+      # For +path:line+ items (example granularity), also matches pins/globs against the file path only.
       def forced_shard_for(path)
         rel = path.to_s
         abs = File.expand_path(rel, @root)
+        variants = [rel, abs]
+        if (fp = TimingKeys.file_part_for_constraint(rel))
+          variants << fp
+          variants << File.expand_path(fp, @root)
+        end
+        variants.uniq!
 
         @pin_map.each do |pattern, shard|
           next if pattern.to_s.empty?
 
-          if match_pattern?(pattern.to_s, rel, abs)
-            return shard
+          variants.each do |rel_i|
+            abs_i = File.expand_path(rel_i, @root)
+            return shard if match_pattern?(pattern.to_s, rel_i, abs_i)
           end
         end
 
         @serial_globs.each do |g|
-          if match_pattern?(g, rel, abs)
-            return @serial_shard
+          variants.each do |rel_i|
+            abs_i = File.expand_path(rel_i, @root)
+            return @serial_shard if match_pattern?(g, rel_i, abs_i)
           end
         end
 

data/lib/polyrun/partition/plan.rb

@@ -1,41 +1,48 @@
-require "json"
-
+require_relative "timing_keys"
 require_relative "constraints"
 require_relative "hrw"
 require_relative "min_heap"
 require_relative "stable_shuffle"
-
 module Polyrun
   module Partition
-    # Assigns discrete items (e.g. spec paths) to shards (spec_queue.md).
+    # Assigns discrete items (e.g. spec paths, or +path:line+ example locators) to shards (spec_queue.md).
     #
     # Strategies:
     # - +round_robin+ — sorted paths, assign by index mod +total_shards+.
     # - +random_round_robin+ — Fisher–Yates shuffle (optional +seed+), then same mod assignment.
-    # - +cost_binpack+ (+cost+, +binpack+, +timing+) — LPT greedy binpack using per-path weights;
+    # - +cost_binpack+ (+cost+, +binpack+, +timing+) — LPT greedy binpack using per-item weights;
     #   optional {Constraints} for pins / serial globs before LPT on the rest.
+    #   Default +timing_granularity+ is +file+ (one weight per spec file). Experimental +:example+
+    #   uses +path:line+ locators and per-example weights in the timing JSON.
     # - +hrw+ (+rendezvous+) — rendezvous hashing for minimal remapping when m changes; optional constraints.
     class Plan
       COST_STRATEGIES = %w[cost cost_binpack binpack timing].freeze
       HRW_STRATEGIES = %w[hrw rendezvous].freeze
 
-      attr_reader :items, :total_shards, :strategy, :seed, :constraints
+      attr_reader :items, :total_shards, :strategy, :seed, :constraints, :timing_granularity
 
-      def initialize(items:, total_shards:, strategy: "round_robin", seed: nil, costs: nil, constraints: nil, root: nil)
-        @items = items.map(&:to_s).freeze
+      def initialize(items:, total_shards:, strategy: "round_robin", seed: nil, costs: nil, constraints: nil, root: nil, timing_granularity: :file)
+        @timing_granularity = TimingKeys.normalize_granularity(timing_granularity)
+        @root = root ? File.expand_path(root) : Dir.pwd
+        @items = items.map do |x|
+          if @timing_granularity == :example
+            TimingKeys.normalize_locator(x, @root, :example)
+          else
+            x.to_s.strip
+          end
+        end.freeze
         @total_shards = Integer(total_shards)
         raise Polyrun::Error, "total_shards must be >= 1" if @total_shards < 1
 
         @strategy = strategy.to_s
         @seed = seed
-        @root = root ? File.expand_path(root) : Dir.pwd
         @constraints = normalize_constraints(constraints)
         @costs = normalize_costs(costs)
 
         validate_constraints_strategy_combo!
         if cost_strategy? && (@costs.nil? || @costs.empty?)
           raise Polyrun::Error,
-            "strategy #{@strategy} requires a timing map (path => seconds), e.g. merged polyrun_timing.json"
+            "strategy #{@strategy} requires a timing map (path => seconds or path:line => seconds), e.g. merged polyrun_timing.json"
         end
       end
 
@@ -85,24 +92,14 @@ module Polyrun
           "seed" => seed,
           "paths" => shard(shard_index)
         }
+        m["timing_granularity"] = timing_granularity.to_s if timing_granularity == :example
         secs = shard_weight_totals
         m["shard_seconds"] = secs if cost_strategy? || (hrw_strategy? && secs.any? { |x| x > 0 })
         m
       end
 
-      def self.load_timing_costs(path)
-        abs = File.expand_path(path.to_s, Dir.pwd)
-        return {} unless File.file?(abs)
-
-        data = JSON.parse(File.read(abs))
-        return {} unless data.is_a?(Hash)
-
-        out = {}
-        data.each do |k, v|
-          key = File.expand_path(k.to_s, Dir.pwd)
-          out[key] = v.to_f
-        end
-        out
+      def self.load_timing_costs(path, granularity: :file, root: nil)
+        TimingKeys.load_costs_json_file(path, granularity, root: root)
       end
 
       def self.cost_strategy?(name)
@@ -134,7 +131,12 @@ module Polyrun
 
         c = {}
         costs.each do |k, v|
-          key = File.expand_path(k.to_s, @root)
+          key =
+            if @timing_granularity == :example
+              TimingKeys.normalize_locator(k.to_s, @root, :example)
+            else
+              File.expand_path(k.to_s, @root)
+            end
           c[key] = v.to_f
         end
         c
@@ -161,19 +163,27 @@ module Polyrun
       end
 
       def weight_for(path)
-        abs = File.expand_path(path.to_s, @root)
-        return @costs[abs] if @costs&.key?(abs)
+        key = cost_lookup_key(path.to_s)
+        return @costs[key] if @costs&.key?(key)
 
         default_weight
       end
 
       def weight_for_optional(path)
-        abs = File.expand_path(path.to_s, @root)
-        return @costs[abs] if @costs&.key?(abs)
+        key = cost_lookup_key(path.to_s)
+        return @costs[key] if @costs&.key?(key)
 
         0.0
       end
 
+      def cost_lookup_key(path)
+        if @timing_granularity == :example
+          TimingKeys.normalize_locator(path, @root, :example)
+        else
+          File.expand_path(path, @root)
+        end
+      end
+
       def cost_shards
         @cost_shards ||= build_lpt_buckets
       end

data/lib/polyrun/partition/timing_keys.rb

@@ -0,0 +1,85 @@
+require "json"
+
+require_relative "../log"
+
+module Polyrun
+  module Partition
+    # Normalizes partition item keys and timing JSON keys for +file+ vs experimental +example+ granularity.
+    #
+    # * +file+ — one item per spec file; keys are absolute paths (see {#canonical_file_path}).
+    # * +example+ — one item per example (RSpec-style +path:line+); keys are +"#{absolute_path}:#{line}+".
+    module TimingKeys
+      module_function
+
+      # Resolves the parent directory with +File.realpath+ so +/var/...+ and +/private/var/...+ (macOS
+      # tmpdirs) and symlink segments map to one key for the same file.
+      def canonical_file_path(abs_path)
+        dir = File.dirname(abs_path)
+        base = File.basename(abs_path)
+        File.join(File.realpath(dir), base)
+      rescue SystemCallError
+        abs_path
+      end
+
+      # @return [:file, :example]
+      def normalize_granularity(value)
+        case value.to_s.strip.downcase
+        when "example", "examples"
+          :example
+        else
+          :file
+        end
+      end
+
+      # File path only (for partition constraints) when +item+ is +path:line+.
+      def file_part_for_constraint(item)
+        s = item.to_s
+        m = s.match(/\A(.+):(\d+)\z/)
+        return nil unless m && m[2].match?(/\A\d+\z/)
+
+        m[1]
+      end
+
+      # Normalize a path or +path:line+ locator relative to +root+ for cost maps and +Plan+ items.
+      def normalize_locator(raw, root, granularity)
+        s = raw.to_s.strip
+        return canonical_file_path(File.expand_path(s, root)) if s.empty?
+
+        if granularity == :example && (m = s.match(/\A(.+):(\d+)\z/)) && m[2].match?(/\A\d+\z/)
+          fp = canonical_file_path(File.expand_path(m[1], root))
+          return "#{fp}:#{m[2]}"
+        end
+
+        canonical_file_path(File.expand_path(s, root))
+      end
+
+      # Loads merged timing JSON (+path => seconds+ or +path:line => seconds+).
+      #
+      # @param root [String, nil] directory for normalizing relative keys (default: +Dir.pwd+). Use the
+      #   same working directory (or pass the same +root+ as {Partition::Plan}+'s +root+) as when
+      #   generating the timing file so keys align.
+      def load_costs_json_file(path, granularity, root: nil)
+        abs = File.expand_path(path.to_s, Dir.pwd)
+        return {} unless File.file?(abs)
+
+        data = JSON.parse(File.read(abs))
+        return {} unless data.is_a?(Hash)
+
+        g = normalize_granularity(granularity)
+        root = File.expand_path(root || Dir.pwd)
+        out = {}
+        data.each do |k, v|
+          key = normalize_locator(k.to_s, root, g)
+          fv = v.to_f
+          if out.key?(key) && out[key] != fv
+            Polyrun::Log.warn(
+              "polyrun: timing JSON duplicate key #{key.inspect} after normalize (#{out[key]} vs #{fv}); using #{fv}"
+            )
+          end
+          out[key] = fv
+        end
+        out
+      end
+    end
+  end
+end

data/lib/polyrun/prepare/assets.rb

@@ -1,6 +1,6 @@
 require "digest/md5"
 require "fileutils"
-require "open3"
+require_relative "../process_stdio"
 
 module Polyrun
   module Prepare
@@ -41,14 +41,21 @@ module Polyrun
       end
 
       # Shells out to +bin/rails assets:precompile+ when +rails_root+ contains +bin/rails+.
+      # +silent: true+ discards child stdio (+File::NULL+); +silent: false+ inherits the terminal.
       def precompile!(rails_root:, silent: true)
         exe = File.join(rails_root, "bin", "rails")
         raise Polyrun::Error, "Prepare::Assets: no #{exe}" unless File.executable?(exe)
 
-        cmd = [exe, "assets:precompile"]
-        _out, err, st = Open3.capture3(*cmd, chdir: rails_root)
-        Polyrun::Log.warn err if !silent && !err.empty?
-        raise Polyrun::Error, "assets:precompile failed: #{err}" unless st.success?
+        st, out, err = Polyrun::ProcessStdio.spawn_wait(
+          nil,
+          exe,
+          "assets:precompile",
+          chdir: rails_root,
+          silent: silent
+        )
+        unless st.success?
+          raise Polyrun::Error, Polyrun::ProcessStdio.format_failure_message("assets:precompile", st, out, err)
+        end
 
         true
       end

data/lib/polyrun/process_stdio.rb

@@ -0,0 +1,91 @@
+require "tempfile"
+
+module Polyrun
+  # Run a subprocess without +Open3+ pipe reader threads (avoids noisy +IOError+s on SIGINT when
+  # streams close). By default stdin/stdout/stderr are inherited so output streams live and the
+  # child can use the TTY for prompts.
+  module ProcessStdio
+    MAX_FAILURE_CAPTURE_BYTES = 32_768
+
+    class << self
+      # @param env [Hash, nil] optional environment for the child (only forwarded when a Hash)
+      # @param argv [Array<String>] command argv
+      # @param silent [Boolean] if true, connect stdin/stdout/stderr to +File::NULL+ (no terminal output;
+      #   non-interactive). Still no Open3 pipe threads.
+      # @return [Process::Status]
+      def inherit_stdio_spawn_wait(env, *argv, chdir: nil, silent: false)
+        st, = spawn_wait(env, *argv, chdir: chdir, silent: silent)
+        st
+      end
+
+      # Like {#inherit_stdio_spawn_wait}, but returns captured stdout/stderr when +silent+ is true.
+      # On success those strings are empty (not read). When +silent+ is false, output goes to the TTY
+      # and returned captures are empty.
+      #
+      # @return [Array(Process::Status, String, String)] status, stdout capture, stderr capture
+      def spawn_wait(env, *argv, chdir: nil, silent: false)
+        args = spawn_argv(env, *argv)
+        return spawn_wait_inherit(args, chdir) unless silent
+
+        spawn_wait_silent(args, chdir)
+      end
+
+      # Builds a diagnostic string for failed subprocesses (used when +silent: true+ hid live output).
+      def format_failure_message(label, status, stdout, stderr)
+        msg = "#{label} failed (exit #{status.exitstatus})"
+        s = stdout.to_s
+        e = stderr.to_s
+        msg << "\n--- stdout ---\n#{s}" unless s.strip.empty?
+        msg << "\n--- stderr ---\n#{e}" unless e.strip.empty?
+        msg
+      end
+
+      private
+
+      def spawn_argv(env, *argv)
+        a = []
+        a << env if env.is_a?(Hash)
+        a.concat(argv)
+        a
+      end
+
+      def spawn_wait_inherit(args, chdir)
+        opts = {in: :in, out: :out, err: :err}
+        opts[:chdir] = chdir if chdir
+        pid = Process.spawn(*args, **opts)
+        st = Process.wait2(pid).last
+        [st, "", ""]
+      end
+
+      def spawn_wait_silent(args, chdir)
+        Tempfile.create("polyrun-out") do |tfout|
+          Tempfile.create("polyrun-err") do |tferr|
+            tfout.close
+            tferr.close
+            out_path = tfout.path
+            err_path = tferr.path
+            opts = {in: File::NULL, out: out_path, err: err_path}
+            opts[:chdir] = chdir if chdir
+            pid = Process.spawn(*args, **opts)
+            st = Process.wait2(pid).last
+            if st.success?
+              [st, "", ""]
+            else
+              out = File.binread(out_path)
+              err = File.binread(err_path)
+              [st, truncate_failure_capture(out), truncate_failure_capture(err)]
+            end
+          end
+        end
+      end
+
+      def truncate_failure_capture(bytes)
+        s = bytes.to_s
+        return s if s.bytesize <= MAX_FAILURE_CAPTURE_BYTES
+
+        tail = s.byteslice(-MAX_FAILURE_CAPTURE_BYTES, MAX_FAILURE_CAPTURE_BYTES)
+        "... (#{s.bytesize} bytes total; showing last #{MAX_FAILURE_CAPTURE_BYTES} bytes)\n" + tail
+      end
+    end
+  end
+end

data/lib/polyrun/rspec.rb

@@ -11,5 +11,24 @@ module Polyrun
         Polyrun::Data::ParallelProvisioning.run_suite_hooks!
       end
     end
+
+    # Experimental: add {Timing::RSpecExampleFormatter} and write per-example JSON (see +timing_granularity: example+).
+    # With +output_path:+, that path is used directly (no +ENV+ mutation). Without it, the formatter
+    # reads +ENV["POLYRUN_EXAMPLE_TIMING_OUT"]+ or defaults to +polyrun_timing_examples.json+.
+    def install_example_timing!(output_path: nil)
+      require_relative "timing/rspec_example_formatter"
+      fmt =
+        if output_path
+          op = output_path
+          Class.new(Polyrun::Timing::RSpecExampleFormatter) do
+            define_method(:timing_output_path) { op }
+          end
+        else
+          Polyrun::Timing::RSpecExampleFormatter
+        end
+      ::RSpec.configure do |config|
+        config.add_formatter fmt
+      end
+    end
   end
 end

data/lib/polyrun/templates/POLYRUN.md

@@ -25,7 +25,7 @@ Adjust `--workers` or use `bin/rspec_parallel` if your repo provides a wrapper.
 ### Model B — matrix: one shard per job
 
 - Matrix sets `POLYRUN_SHARD_INDEX` and `POLYRUN_SHARD_TOTAL` explicitly (many runners do not set `CI_NODE_*` by default).
-- Each job runs `polyrun build-paths`, `polyrun plan`, then `bundle exec rspec` for that shard only (see `bin/polyrun-rspec` or `bin/rspec_ci_shard` patterns).
+- Each job runs `polyrun ci-shard-run -- …` (e.g. `-- bundle exec rspec` or `ci-shard-rspec`), or `build-paths` + `plan` + your runner manually. Legacy: `bin/polyrun-rspec` or `bin/rspec_ci_shard` patterns.
 - Upload `coverage/polyrun-fragment-<shard>.json` per job; a `merge-coverage` job downloads all fragments and merges.
 
 Do not combine Model A and Model B in one workflow without a documented reason (nested parallelism and duplicate merges).

data/lib/polyrun/templates/ci_matrix.polyrun.yml

@@ -1,5 +1,8 @@
 # Polyrun — partition contract for CI matrix (one job per POLYRUN_SHARD_INDEX).
-# Each matrix row: set POLYRUN_SHARD_INDEX and POLYRUN_SHARD_TOTAL; run build-paths, plan, rspec.
+# Each matrix row: set POLYRUN_SHARD_INDEX and POLYRUN_SHARD_TOTAL; run:
+#   bundle exec polyrun -c polyrun.yml ci-shard-run -- bundle exec rspec
+# (or ci-shard-rspec; or e.g. ci-shard-run -- bundle exec polyrun quick).
+# Equivalent to build-paths, plan --shard/--total, then run that command with this slice's paths.
 # A separate CI job downloads coverage/polyrun-fragment-*.json and runs merge-coverage.
 # Do not use parallel-rspec with multiple workers inside the same matrix row unless you intend nested parallelism.
 # See: docs/SETUP_PROFILE.md

data/lib/polyrun/timing/merge.rb

@@ -4,7 +4,8 @@ require_relative "../debug"
 
 module Polyrun
   module Timing
-    # Merges per-shard timing JSON files (spec2 §2.4): path => wall seconds (float).
+    # Merges per-shard timing JSON files (spec2 §2.4): path => wall seconds (float), or (experimental)
+    # +absolute_path:line+ => seconds for per-example timing.
     # Disjoint suites: values merged by taking the maximum per path when duplicates appear.
     module Merge
       module_function

data/lib/polyrun/timing/rspec_example_formatter.rb

@@ -0,0 +1,53 @@
+require "json"
+
+require "rspec/core/formatters/base_formatter"
+
+module Polyrun
+  module Timing
+    # Experimental: records +absolute_path:line_number+ => wall seconds per example for
+    # {Partition::Plan} +timing_granularity: :example+ and +merge-timing+.
+    #
+    # Use after RSpec is loaded:
+    #   require "polyrun/timing/rspec_example_formatter"
+    #   RSpec.configure { |c| c.add_formatter Polyrun::Timing::RSpecExampleFormatter }
+    # Or {Polyrun::RSpec.install_example_timing!} (+output_path:+ avoids touching +ENV+).
+    #
+    # Default output path: +ENV["POLYRUN_EXAMPLE_TIMING_OUT"]+ if set, else +polyrun_timing_examples.json+.
+    class RSpecExampleFormatter < RSpec::Core::Formatters::BaseFormatter
+      RSpec::Core::Formatters.register self, :example_finished, :close
+
+      def initialize(output)
+        super
+        @times = {}
+      end
+
+      def example_finished(notification)
+        ex = notification.example
+        result = ex.execution_result
+        return if result.pending?
+
+        t = result.run_time
+        return unless t
+
+        path = ex.metadata[:absolute_path]
+        return unless path
+
+        line = ex.metadata[:line_number]
+        return unless line
+
+        key = "#{File.expand_path(path)}:#{line}"
+        cur = @times[key]
+        @times[key] = cur ? [cur, t].max : t
+      end
+
+      def close(_notification)
+        File.write(timing_output_path, JSON.pretty_generate(@times))
+      end
+
+      # Override in a subclass from {Polyrun::RSpec.install_example_timing!(output_path: ...)}.
+      def timing_output_path
+        ENV["POLYRUN_EXAMPLE_TIMING_OUT"] || "polyrun_timing_examples.json"
+      end
+    end
+  end
+end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/polyrun.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.1.0"
 
-  spec.files = Dir["lib/**/*", "sig/**/*.rbs", "bin/polyrun", "README.md", "docs/SETUP_PROFILE.md", "LICENSE", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md", "polyrun.gemspec"].reject { |f| File.directory?(f) }
+  spec.files = Dir["lib/**/*", "sig/**/*.rbs", "bin/polyrun", "README.md", "CHANGELOG.md", "docs/SETUP_PROFILE.md", "LICENSE", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md", "polyrun.gemspec"].reject { |f| File.directory?(f) }
   spec.bindir = "bin"
   spec.executables = ["polyrun"]
   spec.require_paths = ["lib"]

data/sig/polyrun/rspec.rbs

@@ -1,5 +1,7 @@
 module Polyrun
   module RSpec
     def self.install_parallel_provisioning!: (untyped rspec_config) -> void
+
+    def self.install_example_timing!: (?output_path: String? ) -> void
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -156,6 +156,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - LICENSE
@@ -165,6 +166,7 @@ files:
 - docs/SETUP_PROFILE.md
 - lib/polyrun.rb
 - lib/polyrun/cli.rb
+- lib/polyrun/cli/ci_shard_run_command.rb
 - lib/polyrun/cli/coverage_commands.rb
 - lib/polyrun/cli/coverage_merge_io.rb
 - lib/polyrun/cli/database_commands.rb
@@ -226,8 +228,10 @@ files:
 - lib/polyrun/partition/plan_lpt.rb
 - lib/polyrun/partition/plan_sharding.rb
 - lib/polyrun/partition/stable_shuffle.rb
+- lib/polyrun/partition/timing_keys.rb
 - lib/polyrun/prepare/artifacts.rb
 - lib/polyrun/prepare/assets.rb
+- lib/polyrun/process_stdio.rb
 - lib/polyrun/queue/file_store.rb
 - lib/polyrun/queue/file_store_pending.rb
 - lib/polyrun/quick.rb
@@ -248,6 +252,7 @@ files:
 - lib/polyrun/templates/minimal_gem.polyrun.yml
 - lib/polyrun/templates/rails_prepare.polyrun.yml
 - lib/polyrun/timing/merge.rb
+- lib/polyrun/timing/rspec_example_formatter.rb
 - lib/polyrun/timing/summary.rb
 - lib/polyrun/version.rb
 - polyrun.gemspec