polyrun 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd8b178e07e0cf6648284d59d5b8f58a5feceeb2c7570edfd381aafaed207cb
-  data.tar.gz: cd2846dc77b56bccf0ac411fcc4f6a2a7aaf2e106609172e84299c2a1d253f64
+  metadata.gz: 04bfc3ed1a2c01072864dd179decce4d13c68221bba4da0964f4ea600401b57c
+  data.tar.gz: df02fc828fb8ac8c9cf3792ae08420ee87d328a89d79a7eeec26c9e239506ee4
 SHA512:
-  metadata.gz: c9a71f317d28ce3dcdf25d9c8e08221e71eadb2cf044217170ca0ba08cdc22cb702e6adaf02383d4e6089fa2fdddc94198cc420f031f53186715b67c14c92567
-  data.tar.gz: 81469ea975e78befbf6c66e3482e5c6006c11bb8b1806a079545a00ac057f250d49323aeab6685e8eaec22ff65e5aa72fb28aaca688365048483650d3c78de00
+  metadata.gz: 378921ebc46b80562c5ae4bb529a3035eed7366cbfbcffd9a5c4bcb1d18f1c1fe6b737dfcc580c9b7e3fb1ce4360ac9ad04c7a7edbc50e4763a2e5430a61c873
+  data.tar.gz: 552545582ab8c34e1411834d5f5ef6d1b6f1d022ead68746059b709cd04d733c6d778b13621c003ec2f4525367bdb5e849577d109e2e04835fcf9b12407bf2ef

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## 1.4.0 (2026-04-16)
+
+- Add `hooks:` in `polyrun.yml` — shell commands for `before_suite` / `after_suite`, `before_shard` / `after_shard`, `before_worker` / `after_worker` (RSpec-style YAML keys `before(:suite)`, `before(:all)`, `before(:each)` accepted). Wire hooks into `run-shards`, `parallel-rspec`, and `ci-shard-*`.
+- Add `hooks.ruby` / `hooks.ruby_file` and `Polyrun::Hooks::Dsl` (`before(:suite)` … `after(:each)` blocks); worker Ruby hooks run in the child via `ruby -e` + `POLYRUN_HOOKS_RUBY_FILE`.
+- Add `polyrun hook run <phase>` (`--shard` / `--total` optional). Set `POLYRUN_HOOKS_DISABLE=1` to skip hooks during orchestration only; `hook run` still executes.
+- On `ci-shard-run` / `ci-shard-rspec`, skip automatic `before_suite` / `after_suite` when `POLYRUN_SHARD_TOTAL` > 1 (matrix); run suite hooks once via `polyrun hook run` or set `POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1` to run them on every matrix job.
+- Document hook phases, matrix vs suite, and `after_shard` ordering in `README.md`; list `Polyrun::Hooks` and `Polyrun::Hooks::Dsl` in the library section.
+
+## 1.3.0 (2026-04-15)
+
+- Add safe parsing for `ci-shard-run` / `ci-shard-rspec` `--shard-processes` and `--workers` (warn + exit 2 on missing or non-integer values).
+- Fix `shard_child_env` when `matrix_total > 1` and `matrix_index` is nil: omit `POLYRUN_SHARD_MATRIX_*` and warn (avoid `Integer(nil)`).
+- Document in `polyrun help` that `POLYRUN_SHARD_PROCESSES` and ci-shard `--workers` / `--shard-processes` are local processes per matrix job, distinct from `POLYRUN_WORKERS` / `run-shards`.
+- BREAKING: Multi-worker shard runs may emit coverage JSON fragments whose basenames include `shard*` and `worker*` segments; `merge-coverage` still matches `polyrun-fragment-*.json`.
+
 ## 1.2.0 (2026-04-15)
 
 - Add `polyrun config <dotted.path>` to print values from `Polyrun::Config::Effective` (same effective tree as runtime: arbitrary YAML paths, merged `prepare.env.<KEY>` as for `polyrun prepare`, resolved `partition.shard_index`, `partition.shard_total`, `partition.timing_granularity`, and `workers`).

data/README.md

@@ -25,6 +25,61 @@ Capybara and Playwright stay in your application; Polyrun does not replace brows
 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`.
 
+### Hooks (`hooks:` in `polyrun.yml`)
+
+Optional **shell** commands and/or a **Ruby DSL** file for instrumentation (telemetry, Slack, logging, manual debugging). Names mirror RSpec’s API (`before(:suite)`, `before(:all)`, `before(:each)`), but **Polyrun hooks are about process orchestration**, not RSpec example groups. Below, **suite / shard / worker** mean Polyrun’s model unless stated otherwise.
+
+#### What “suite”, “shard”, and “worker” mean
+
+| Term | Process | Meaning |
+|------|---------|---------|
+| **Suite** | **Parent** only | One **orchestration run** on a single machine: a single `polyrun run-shards` / `parallel-rspec` / `ci-shard-run` (with **one** global shard, see below). `before_suite` runs once before any worker is started; `after_suite` runs once after all workers have exited and (when used) merge-coverage has finished. This is **not** the same as “the whole RSpec suite in one process”—with `--workers N`, RSpec runs in **N separate processes**, each with its own examples. |
+| **Shard** | **Parent** only | One **partition** of the path list for this run, identified by `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL` **for that parallel layout** (0 … N−1 for `run-shards` with N workers). `before_shard` runs in the parent **immediately before** `Process.spawn` for that index; `after_shard` runs **after** that child has exited. The parent **waits workers in shard index order** (0, then 1, …), so `after_shard` runs in that order—not in “who finished first” order if workers overlap in time. Empty partitions are skipped (no spawn, no hooks). |
+| **Worker** | **Child** OS process | The process that runs your command after `--` (e.g. `bundle exec rspec …`). `before_worker` / `after_worker` run **in that child**, directly before and after the test command. **Individual examples run only after `before_worker` completes** (inside the same process as RSpec/Minitest). |
+
+**CI matrix** (`POLYRUN_SHARD_TOTAL` > 1, one job per index): each job is a **global shard**, not a full “suite” in the pipeline sense. **`ci-shard-run` / `ci-shard-rspec` with one process per job do not run `before_suite` / `after_suite` automatically**—otherwise they would run once per matrix cell. Put pipeline-wide setup/teardown in a **separate CI step** (e.g. `bin/polyrun hook run before_suite` and `hook run after_suite` once), or set `POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1` to restore the old behaviour (suite hooks on every matrix job). **`before_shard` / `after_shard` / worker hooks still run** per job, with `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL` set from the matrix. A **single** non-matrix `ci-shard-run` (`POLYRUN_SHARD_TOTAL` is 1) still runs suite hooks like `run-shards --workers 1`. Fan-out on one host (`--shard-processes` > 1) still runs **`before_suite` / `after_suite` once** for that job, around the local workers.
+
+#### Lifecycle (typical `run-shards` with multiple workers)
+
+```text
+[Parent]  before_suite
+[Parent]  for each shard index i that has paths:
+            before_shard(i) → spawn worker i
+[Child i] before_worker →  test runner starts → examples run → runner exits
+[Parent]  after_shard(i)   (parent waits children in shard index order 0…N−1, not global finish order)
+[Parent]  merge-coverage (if requested)
+[Parent]  after_suite
+```
+
+`after_worker` runs in the child after the test command exits, before the parent’s `after_shard`.
+
+#### Order and priority within one phase
+
+1. **Ruby DSL, then shell (YAML)** — For the same phase (e.g. `before_suite`), all **Ruby** blocks from `hooks.ruby` run first, then every **shell** command from YAML for that phase.
+2. **Multiple Ruby blocks** — In one DSL file, registrations run in **source order** (e.g. two `before(:suite)` blocks run top to bottom).
+3. **Multiple shell commands** — Use a **YAML list**; entries run in list order:
+   ```yaml
+   before_suite:
+     - echo first
+     - echo second
+   ```
+4. **Duplicate YAML keys** — Do **not** repeat the same key (e.g. two `before_suite:` lines). Parsers may keep only one value; behaviour is undefined. Prefer a **list** under a single key.
+5. **Failure** — If any step in a phase fails (non-zero exit from shell; uncaught error in Ruby), orchestration stops or marks failure per existing `run-shards` rules; `after_worker` shell steps use `|| true` so a failing teardown does not mask the test exit code (Ruby `after_worker` is wrapped similarly in the worker script).
+
+Environment includes `POLYRUN_HOOK_PHASE`, `POLYRUN_HOOK=1`, `POLYRUN_HOOK_ORCHESTRATOR` (`1` in parent, `0` in workers), `POLYRUN_SHARD_*`, and `POLYRUN_SUITE_EXIT_STATUS` on `after_suite`. Worker children get `POLYRUN_HOOKS_RUBY_FILE` when using the Ruby DSL. Set `POLYRUN_HOOKS_DISABLE=1` to skip hooks during `run-shards` / `parallel-rspec` / `ci-shard-*` (orchestration only); `polyrun hook run` still executes hooks. **`POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1`** — when set, run `before_suite` / `after_suite` on every CI matrix job (not recommended for expensive global setup).
+
+**YAML keys (shell) and RSpec-style names in YAML:**
+
+| YAML key | DSL in `hooks.ruby` | When |
+|----------|----------------------|------|
+| `before_suite` / `after_suite` | `before(:suite)` / `after(:suite)` | Parent: once per orchestration on one host; **skipped** for `ci-shard-run` when `POLYRUN_SHARD_TOTAL` > 1 unless `POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1` (see matrix paragraph above) |
+| `before_shard` / `after_shard` | `before(:all)` / `after(:all)` | Parent: per shard index (spawn / after exit) |
+| `before_worker` / `after_worker` | `before(:each)` / `after(:each)` | Child: around the test command |
+
+**Ruby DSL (`hooks.ruby` or `hooks.ruby_file`):** path to a `.rb` file (relative to the project root). Blocks receive a `Hash` with **string keys** (same env as shell hooks). Worker-phase Ruby hooks run in the child via `ruby -e 'require "polyrun"; …'`.
+
+Run one phase by hand: `bin/polyrun hook run before_suite` (optional `--shard N --total M`). YAML may use quoted keys such as `"before(:suite)"` instead of `before_suite`.
+
 Quick CLI samples:
 
 If the current directory already has `polyrun.yml` or `config/polyrun.yml`, you can omit `-c` (same as `Config.load` default discovery). Pass `-c PATH` or set `POLYRUN_CONFIG` when the file lives elsewhere or uses another name.
@@ -41,6 +96,7 @@ bin/polyrun env --shard 0 --total 4   # print DATABASE_URL exports from polyrun.
 bin/polyrun init --list
 bin/polyrun init --profile gem -o polyrun.yml   # starter YAML; see docs/SETUP_PROFILE.md
 bin/polyrun quick   # Polyrun::Quick examples under spec/polyrun_quick/ or test/polyrun_quick/
+bin/polyrun hook run before_suite   # run hooks.before_suite from polyrun.yml (manual / CI)
 ```
 
 ### Matrix shards and timing
@@ -87,6 +143,8 @@ 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::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). |
 
 ## Development
 

data/lib/polyrun/cli/ci_shard_hooks.rb

@@ -0,0 +1,121 @@
+module Polyrun
+  class CLI
+    # Suite / shard / worker shell hooks for +ci-shard-run+ / +ci-shard-rspec+.
+    module CiShardHooks
+      private
+
+      # rubocop:disable Metrics/AbcSize -- suite hooks + spawn/wait + failure paths
+      def ci_shard_run_fanout!(ctx)
+        hook_cfg = Polyrun::Hooks.from_config(ctx[:cfg])
+        suite_started = false
+        exit_code = 1
+
+        begin
+          env_suite = ENV.to_h.merge(
+            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+            "POLYRUN_SHARD_TOTAL" => ctx[:workers].to_s
+          )
+          code = hook_cfg.run_phase_if_enabled(:before_suite, env_suite)
+          return code if code != 0
+
+          suite_started = true
+
+          pids, spawn_err = run_shards_spawn_workers(ctx, hook_cfg)
+          if spawn_err
+            exit_code = spawn_err
+            return spawn_err
+          end
+          return 1 if pids.empty?
+
+          run_shards_warn_interleaved(ctx[:parallel], pids.size)
+          shard_results, wait_hook_err = run_shards_wait_all_children(pids, hook_cfg, ctx)
+          failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
+
+          if failed.any?
+            Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (some failed)"
+            run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+            exit_code = 1
+            exit_code = 1 if wait_hook_err != 0
+            return exit_code
+          end
+
+          exit_code = (wait_hook_err == 0) ? 0 : 1
+          Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (exit 0)" if exit_code == 0
+          exit_code
+        ensure
+          if suite_started
+            env_after = ENV.to_h.merge(
+              "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+              "POLYRUN_SHARD_TOTAL" => ctx[:workers].to_s,
+              "POLYRUN_SUITE_EXIT_STATUS" => exit_code.to_s
+            )
+            hook_cfg.run_phase_if_enabled(:after_suite, env_after)
+          end
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # One matrix shard, one OS process: same hook phases as +run-shards+ with +--workers 1+ (no +exec+ when hooks exist).
+      # rubocop:disable Metrics/AbcSize -- suite / shard / worker lifecycle
+      def ci_shard_run_single!(cmd, paths, cfg, pc, _config_path)
+        hook_cfg = Polyrun::Hooks.from_config(cfg)
+        if hook_cfg.empty? || Polyrun::Hooks.disabled?
+          exec(*cmd, *paths)
+        end
+
+        si = Polyrun::Config::Resolver.resolve_shard_index(pc)
+        st = Polyrun::Config::Resolver.resolve_shard_total(pc)
+        suite_started = false
+        exit_code = 1
+        # Distributed CI matrix (N > 1 global shards): each job is one shard; suite hooks are pipeline-wide.
+        # Run them once via +polyrun hook run before_suite+ / +after_suite+ (e.g. dedicated job), or set
+        # +POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1+ to run suite hooks on every matrix job.
+        matrix_shards = st > 1
+        run_suite_hooks = !matrix_shards || Polyrun::Hooks.suite_per_matrix_job?
+
+        begin
+          env_orch = ENV.to_h.merge(
+            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+            "POLYRUN_SHARD_INDEX" => si.to_s,
+            "POLYRUN_SHARD_TOTAL" => st.to_s
+          )
+          if run_suite_hooks
+            code = hook_cfg.run_phase_if_enabled(:before_suite, env_orch)
+            return code if code != 0
+
+            suite_started = true
+          end
+
+          code = hook_cfg.run_phase_if_enabled(:before_shard, env_orch)
+          return code if code != 0
+
+          mx, mt = ci_shard_matrix_context(pc, 1)
+          child_env = shard_child_env(cfg: cfg, workers: 1, shard: 0, matrix_index: mx, matrix_total: mt)
+          child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
+          child_env = hook_cfg.merge_worker_ruby_env(child_env)
+
+          if hook_cfg.worker_hooks? && !Polyrun::Hooks.disabled?
+            system(child_env, "sh", "-c", hook_cfg.build_worker_shell_script(cmd, paths))
+          else
+            system(child_env, *cmd, *paths)
+          end
+          exit_code = $?.exitstatus
+
+          rc = hook_cfg.run_phase_if_enabled(:after_shard, env_orch.merge(
+            "POLYRUN_WORKER_EXIT_STATUS" => exit_code.to_s
+          ))
+          exit_code = rc if rc != 0
+
+          exit_code
+        ensure
+          if suite_started
+            hook_cfg.run_phase_if_enabled(:after_suite, env_orch.merge(
+              "POLYRUN_SUITE_EXIT_STATUS" => exit_code.to_s
+            ))
+          end
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end

data/lib/polyrun/cli/ci_shard_run_command.rb

@@ -1,14 +1,23 @@
 require "shellwords"
 
+require_relative "ci_shard_hooks"
+
 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 +--+).
     #
+    # With +--shard-processes M+ (or +partition.shard_processes+ / +POLYRUN_SHARD_PROCESSES+), fans out
+    # +M+ OS processes on this host, each running a subset of this shard's paths (NxM: +N+ matrix jobs × +M+
+    # processes). Child processes get local +POLYRUN_SHARD_INDEX+ / +POLYRUN_SHARD_TOTAL+ (+0..M-1+, +M+);
+    # when +N+ > 1, also +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+ for unique coverage fragments.
+    #
     # 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
+      include CiShardHooks
+
       private
 
       # @return [Array(Array<String>, Integer)] [paths, 0] on success, or [nil, exit_code] on failure
@@ -25,6 +34,42 @@ module Polyrun
         [paths, 0]
       end
 
+      def ci_shard_local_plan!(paths, workers)
+        Polyrun::Partition::Plan.new(
+          items: paths,
+          total_shards: workers,
+          strategy: "round_robin",
+          root: Dir.pwd
+        )
+      end
+
+      # When +N+ > 1 and +M+ > 1, pass matrix index/total for coverage fragment names; else nil (see +shard_child_env+).
+      def ci_shard_matrix_context(pc, shard_processes)
+        n = resolve_shard_total(pc)
+        return [nil, nil] if n <= 1 || shard_processes <= 1
+
+        [resolve_shard_index(pc), n]
+      end
+
+      def ci_shard_fanout_context(cfg:, pc:, paths:, shard_processes:, cmd:, config_path:)
+        plan = ci_shard_local_plan!(paths, shard_processes)
+        mx, mt = ci_shard_matrix_context(pc, shard_processes)
+        {
+          workers: shard_processes,
+          cmd: cmd,
+          cfg: cfg,
+          plan: plan,
+          run_t0: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          parallel: true,
+          merge_coverage: false,
+          merge_output: nil,
+          merge_format: nil,
+          config_path: config_path,
+          matrix_shard_index: mx,
+          matrix_shard_total: mt
+        }
+      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)
@@ -42,10 +87,26 @@ module Polyrun
         end
         cmd = Shellwords.split(cmd.first) if cmd.size == 1 && cmd.first.include?(" ")
 
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
         paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-run")
         return code if code != 0
 
-        exec(*cmd, *paths)
+        if shard_processes <= 1
+          return ci_shard_run_single!(cmd, paths, cfg, pc, config_path)
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-run: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
       end
 
       # Same as +ci-shard-run -- bundle exec rspec+ with an optional second segment for RSpec-only flags:
@@ -55,10 +116,28 @@ module Polyrun
         plan_argv = sep ? argv[0...sep] : argv
         rspec_argv = sep ? argv[(sep + 1)..] : []
 
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
         paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-rspec")
         return code if code != 0
 
-        exec("bundle", "exec", "rspec", *rspec_argv, *paths)
+        cmd = ["bundle", "exec", "rspec", *rspec_argv]
+
+        if shard_processes <= 1
+          return ci_shard_run_single!(cmd, paths, cfg, pc, config_path)
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-rspec: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
       end
     end
   end

data/lib/polyrun/cli/ci_shard_run_parse.rb

@@ -0,0 +1,68 @@
+module Polyrun
+  class CLI
+    # Parsing for +ci-shard-run+ / +ci-shard-rspec+ plan argv (+--shard-processes+, +--workers+).
+    module CiShardRunParse
+      private
+
+      # Strips +--shard-processes+ / +--workers+ from +plan_argv+ and returns +[count, exit_code]+.
+      # +exit_code+ is +nil+ on success, +2+ on invalid or missing integer (no exception).
+      # Does not use +OptionParser+ so +plan+ flags (+--shard+, +--total+, …) pass through unchanged.
+      # Note: +--workers+ here means processes for this matrix job (+POLYRUN_SHARD_PROCESSES+), not +run-shards+ +POLYRUN_WORKERS+.
+      def ci_shard_parse_shard_processes!(plan_argv, pc)
+        workers = Polyrun::Config::Resolver.resolve_shard_processes(pc)
+        rest = []
+        i = 0
+        while i < plan_argv.size
+          case plan_argv[i]
+          when "--shard-processes"
+            n, err = ci_shard_parse_positive_int_flag!(plan_argv, i, "--shard-processes")
+            return [nil, err] if err
+
+            workers = n
+            i += 2
+          when "--workers"
+            n, err = ci_shard_parse_positive_int_flag!(plan_argv, i, "--workers")
+            return [nil, err] if err
+
+            workers = n
+            i += 2
+          else
+            rest << plan_argv[i]
+            i += 1
+          end
+        end
+        plan_argv.replace(rest)
+        [workers, nil]
+      end
+
+      # @return [Array(Integer or nil, Integer or nil)] +[value, exit_code]+ — +exit_code+ is +nil+ on success, +2+ on error
+      def ci_shard_parse_positive_int_flag!(argv, i, flag_name)
+        arg = argv[i + 1]
+        if arg.nil?
+          Polyrun::Log.warn "polyrun ci-shard: missing value for #{flag_name}"
+          return [nil, 2]
+        end
+        n = Integer(arg, exception: false)
+        if n.nil?
+          Polyrun::Log.warn "polyrun ci-shard: #{flag_name} must be an integer (got #{arg.inspect})"
+          return [nil, 2]
+        end
+        [n, nil]
+      end
+
+      # @return [Array(Integer, Integer, nil)] +[capped_workers, exit_code]+ — +exit_code+ is +nil+ when OK
+      def ci_shard_normalize_shard_processes(workers)
+        if workers < 1
+          Polyrun::Log.warn "polyrun ci-shard: --shard-processes / --workers must be >= 1"
+          return [workers, 2]
+        end
+        w = workers
+        if w > Polyrun::Config::MAX_PARALLEL_WORKERS
+          Polyrun::Log.warn "polyrun ci-shard: capping --shard-processes / --workers from #{w} to #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
+          w = Polyrun::Config::MAX_PARALLEL_WORKERS
+        end
+        [w, nil]
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -21,7 +21,7 @@ module Polyrun
           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)
-          Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start)
+          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)
           Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
 
           commands:
@@ -32,12 +32,13 @@ 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]
+            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 / claim / ack / status)
+            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!)
+            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

data/lib/polyrun/cli/hooks_command.rb

@@ -0,0 +1,97 @@
+module Polyrun
+  class CLI
+    # +polyrun hook run <phase>+ — run one lifecycle phase from +polyrun.yml+ +hooks:+ (manual debugging / CI).
+    module HooksCommand
+      private
+
+      def cmd_hook(argv, config_path)
+        sub = argv.shift
+        case sub
+        when "run"
+          cmd_hook_run(argv, config_path)
+        when nil, "help", "-h", "--help"
+          print_hook_help
+          0
+        else
+          Polyrun::Log.warn "polyrun hook: unknown subcommand #{sub.inspect} (try: polyrun hook run <phase>)"
+          print_hook_help
+          2
+        end
+      end
+
+      def cmd_hook_run(argv, config_path)
+        phase = argv.shift
+        if phase.nil? || phase == "-h" || phase == "--help"
+          print_hook_help
+          return 2
+        end
+
+        shard, total = hook_run_parse_shard_flags!(argv)
+
+        unless argv.empty?
+          Polyrun::Log.warn "polyrun hook run: unexpected arguments: #{argv.inspect}"
+          return 2
+        end
+
+        phase_sym = Polyrun::Hooks.parse_phase(phase)
+        unless phase_sym && Polyrun::Hooks::PHASES.include?(phase_sym)
+          Polyrun::Log.warn "polyrun hook run: unknown phase #{phase.inspect} (expected: #{Polyrun::Hooks::PHASES.join(", ")})"
+          return 2
+        end
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        hook_cfg = Polyrun::Hooks.from_config(cfg)
+        env = hook_run_env(shard, total)
+
+        hook_cfg.run_phase(phase_sym, env)
+      rescue ArgumentError => e
+        Polyrun::Log.warn "polyrun hook run: #{e.message}"
+        2
+      end
+
+      def hook_run_parse_shard_flags!(argv)
+        shard = nil
+        total = nil
+        while (a = argv.first)
+          case a
+          when "--shard"
+            argv.shift
+            shard = Integer(argv.shift || (raise ArgumentError, "--shard needs a value"))
+          when "--total"
+            argv.shift
+            total = Integer(argv.shift || (raise ArgumentError, "--total needs a value"))
+          else
+            break
+          end
+        end
+        [shard, total]
+      end
+
+      def hook_run_env(shard, total)
+        env = ENV.to_h.merge(
+          "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+          "POLYRUN_HOOK_CLI" => "1"
+        )
+        env["POLYRUN_SHARD_INDEX"] = shard.to_s unless shard.nil?
+        env["POLYRUN_SHARD_TOTAL"] = total.to_s unless total.nil?
+        env
+      end
+
+      def print_hook_help
+        Polyrun::Log.puts <<~HELP
+          usage: polyrun hook run <phase> [--shard N] [--total M]
+
+          Runs hook(s) from polyrun.yml: Ruby DSL (+hooks.ruby+) then shell strings for <phase> (same names as RSpec lifecycle:
+          before_suite / after_suite as before(:suite) / after(:suite); before_shard / after_shard as
+          before(:all) / after(:all); before_worker / after_worker as before(:each) / after(:each)).
+
+          Phases: #{Polyrun::Hooks::PHASES.join(", ")}
+
+          Optional --shard / --total set POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL for the hook process.
+          POLYRUN_HOOKS_DISABLE=1 skips hooks during run-shards / ci-shard only; polyrun hook run still executes.
+          For CI matrix (POLYRUN_SHARD_TOTAL > 1), ci-shard-run skips before_suite / after_suite unless POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1; run those phases here or in a dedicated CI job.
+        HELP
+      end
+    end
+  end
+end

data/lib/polyrun/cli/plan_command.rb

@@ -76,21 +76,31 @@ module Polyrun
         }
       end
 
+      # Partition flags shared by +polyrun plan+ and +queue init+ (excluding +--paths-file+, which each command registers once).
+      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("--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|
+          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
+
+      # Shared by +polyrun plan+ and +queue init+ so partition flags match +Partition::Plan+ / +plan+ JSON.
+      def plan_command_register_options!(opts, ctx)
+        opts.on("--paths-file PATH", String) { |v| ctx[:paths_file] = v }
+        plan_command_register_partition_options!(opts, ctx)
+      end
+
       def plan_command_parse_argv!(argv, ctx)
         OptionParser.new do |opts|
           opts.banner = "usage: polyrun plan [options] [--] [paths...]"
-          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("--seed VAL") { |v| ctx[:seed] = v }
-          opts.on("--paths-file PATH", String) { |v| ctx[:paths_file] = 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|
-            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
+          plan_command_register_options!(opts, ctx)
         end.parse!(argv)
       end