polyrun 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3162ed760c231d4fa78ff396f55f708af13bda62808ba340f3c1494cf2dd97e
-  data.tar.gz: f401bd075462bafa14905c08a996fa46370025be9872f6a4d7aefbfdde251d2d
+  metadata.gz: 04bfc3ed1a2c01072864dd179decce4d13c68221bba4da0964f4ea600401b57c
+  data.tar.gz: df02fc828fb8ac8c9cf3792ae08420ee87d328a89d79a7eeec26c9e239506ee4
 SHA512:
-  metadata.gz: 3d0bf0e8ac88d3d0a007f53ce340c324bcd65c6397b4b67905d428d104ebff3078bc41220873b0b7d741e6cc65be06d5d103f8b8abd64e18ce0dc2d8f3e55bc1
-  data.tar.gz: 42906169eeeae14b3531d870359ce8fe9bd59261770553a6e7e6872e48e47b7b1013709eedea5c176a94ccee5c1e498551e8d6285ffc68b37c51d05169b184b1
+  metadata.gz: 378921ebc46b80562c5ae4bb529a3035eed7366cbfbcffd9a5c4bcb1d18f1c1fe6b737dfcc580c9b7e3fb1ce4360ac9ad04c7a7edbc50e4763a2e5430a61c873
+  data.tar.gz: 552545582ab8c34e1411834d5f5ef6d1b6f1d022ead68746059b709cd04d733c6d778b13621c003ec2f4525367bdb5e849577d109e2e04835fcf9b12407bf2ef

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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).

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,5 +1,7 @@
 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+
@@ -14,6 +16,8 @@ module Polyrun
     # 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
@@ -47,24 +51,6 @@ module Polyrun
         [resolve_shard_index(pc), n]
       end
 
-      def ci_shard_run_fanout!(ctx)
-        pids = run_shards_spawn_workers(ctx)
-        return 1 if pids.empty?
-
-        run_shards_warn_interleaved(ctx[:parallel], pids.size)
-        shard_results = run_shards_wait_all_children(pids)
-        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])
-          return 1
-        end
-
-        Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (exit 0)"
-        0
-      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)
@@ -113,8 +99,7 @@ module Polyrun
         return code if code != 0
 
         if shard_processes <= 1
-          exec(*cmd, *paths)
-          return 0
+          return ci_shard_run_single!(cmd, paths, cfg, pc, config_path)
         end
 
         ctx = ci_shard_fanout_context(
@@ -145,8 +130,7 @@ module Polyrun
         cmd = ["bundle", "exec", "rspec", *rspec_argv]
 
         if shard_processes <= 1
-          exec(*cmd, *paths)
-          return 0
+          return ci_shard_run_single!(cmd, paths, cfg, pc, config_path)
         end
 
         ctx = ci_shard_fanout_context(

data/lib/polyrun/cli/help.rb

@@ -38,6 +38,7 @@ module Polyrun
             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!)
+            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/run_shards_parallel_children.rb

@@ -0,0 +1,92 @@
+module Polyrun
+  class CLI
+    # Spawns and waits on worker processes for +run-shards+ / +ci-shard-*+ fan-out.
+    module RunShardsParallelChildren
+      private
+
+      # @return [Array(Array, Integer, nil)] +[pids, spawn_error_code]+; +spawn_error_code+ is +nil+ when all spawns succeeded
+      # rubocop:disable Metrics/AbcSize -- shard loop: spawn + shard hooks + env
+      def run_shards_spawn_workers(ctx, hook_cfg)
+        workers = ctx[:workers]
+        cmd = ctx[:cmd]
+        cfg = ctx[:cfg]
+        plan = ctx[:plan]
+        parallel = ctx[:parallel]
+        mx = ctx[:matrix_shard_index]
+        mt = ctx[:matrix_shard_total]
+
+        pids = []
+        workers.times do |shard|
+          paths = plan.shard(shard)
+          if paths.empty?
+            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
+            next
+          end
+
+          env_shard = ENV.to_h.merge(
+            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+            "POLYRUN_SHARD_INDEX" => shard.to_s,
+            "POLYRUN_SHARD_TOTAL" => workers.to_s
+          )
+          code = hook_cfg.run_phase_if_enabled(:before_shard, env_shard)
+          if code != 0
+            run_shards_terminate_children!(pids)
+            return [pids, code]
+          end
+
+          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, 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)
+
+          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
+          pid = run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+          pids << {pid: pid, shard: shard}
+          Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
+          Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+        end
+        [pids, nil]
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+        if hook_cfg.worker_hooks? && !Polyrun::Hooks.disabled?
+          Process.spawn(child_env, "sh", "-c", hook_cfg.build_worker_shell_script(cmd, paths))
+        else
+          Process.spawn(child_env, *cmd, *paths)
+        end
+      end
+
+      # @return [Array(Array, Integer)] +[shard_results, after_shard_hook_error_code]+ (0 when all +after_shard+ hooks passed)
+      def run_shards_wait_all_children(pids, hook_cfg, ctx)
+        workers = ctx[:workers]
+        shard_results = []
+        after_hook_err = 0
+        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
+          pids.each do |h|
+            Process.wait(h[:pid])
+            exitstatus = $?.exitstatus
+            ok = $?.success?
+            Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
+            env_after = ENV.to_h.merge(
+              "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+              "POLYRUN_SHARD_INDEX" => h[:shard].to_s,
+              "POLYRUN_SHARD_TOTAL" => workers.to_s,
+              "POLYRUN_WORKER_EXIT_STATUS" => exitstatus.to_s
+            )
+            rc = hook_cfg.run_phase_if_enabled(:after_shard, env_after)
+            after_hook_err = rc if rc != 0 && after_hook_err == 0
+            shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
+          end
+        rescue Interrupt
+          # Do not trap SIGINT: Process.wait raises Interrupt; a trap races and prints Interrupt + SystemExit traces.
+          run_shards_shutdown_on_signal!(pids, 130)
+        rescue SignalException => e
+          raise unless e.signm == "SIGTERM"
+
+          run_shards_shutdown_on_signal!(pids, 143)
+        end
+        [shard_results, after_hook_err]
+      end
+    end
+  end
+end

data/lib/polyrun/cli/run_shards_run.rb

@@ -2,12 +2,14 @@ require "shellwords"
 require "rbconfig"
 
 require_relative "run_shards_planning"
+require_relative "run_shards_parallel_children"
 
 module Polyrun
   class CLI
     # Partition + spawn workers for `polyrun run-shards` (keeps {RunShardsCommand} file small).
     module RunShardsRun
       include RunShardsPlanning
+      include RunShardsParallelChildren
 
       private
 
@@ -18,59 +20,68 @@ module Polyrun
         run_shards_workers_and_merge(ctx)
       end
 
+      # rubocop:disable Metrics/AbcSize -- orchestration: hooks, merge, worker failures
       def run_shards_workers_and_merge(ctx)
-        pids = run_shards_spawn_workers(ctx)
-        return 1 if pids.empty?
-
-        run_shards_warn_interleaved(ctx[:parallel], pids.size)
-
-        shard_results = run_shards_wait_all_children(pids)
-        failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
-
-        Polyrun::Debug.log(format(
-          "run-shards: workers wall time since start: %.3fs",
-          Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
-        ))
+        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
+          if pids.empty?
+            exit_code = 1
+            return 1
+          end
 
-        if ctx[:parallel]
-          Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
-        end
+          run_shards_warn_interleaved(ctx[:parallel], pids.size)
 
-        if failed.any?
-          run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
-          return 1
-        end
+          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] }
 
-        run_shards_merge_or_hint_coverage(ctx)
-      end
+          Polyrun::Debug.log(format(
+            "run-shards: workers wall time since start: %.3fs",
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
+          ))
 
-      def run_shards_spawn_workers(ctx)
-        workers = ctx[:workers]
-        cmd = ctx[:cmd]
-        cfg = ctx[:cfg]
-        plan = ctx[:plan]
-        parallel = ctx[:parallel]
-        mx = ctx[:matrix_shard_index]
-        mt = ctx[:matrix_shard_total]
-
-        pids = []
-        workers.times do |shard|
-          paths = plan.shard(shard)
-          if paths.empty?
-            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
-            next
+          if ctx[:parallel]
+            Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
           end
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
+          if failed.any?
+            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
 
-          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
-          pid = Process.spawn(child_env, *cmd, *paths)
-          pids << {pid: pid, shard: shard}
-          Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
-          Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+          exit_code = run_shards_merge_or_hint_coverage(ctx)
+          exit_code = 1 if wait_hook_err != 0 && 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
-        pids
       end
+      # rubocop:enable Metrics/AbcSize
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
@@ -79,27 +90,6 @@ module Polyrun
         Polyrun::Log.warn "polyrun run-shards: each worker prints its own summary line; the last \"N examples\" line is not a total across shards."
       end
 
-      def run_shards_wait_all_children(pids)
-        shard_results = []
-        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
-          pids.each do |h|
-            Process.wait(h[:pid])
-            exitstatus = $?.exitstatus
-            ok = $?.success?
-            Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
-            shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
-          end
-        rescue Interrupt
-          # Do not trap SIGINT: Process.wait raises Interrupt; a trap races and prints Interrupt + SystemExit traces.
-          run_shards_shutdown_on_signal!(pids, 130)
-        rescue SignalException => e
-          raise unless e.signm == "SIGTERM"
-
-          run_shards_shutdown_on_signal!(pids, 143)
-        end
-        shard_results
-      end
-
       # Best-effort worker teardown then exit. Does not return.
       def run_shards_shutdown_on_signal!(pids, code)
         run_shards_terminate_children!(pids)

data/lib/polyrun/cli.rb

@@ -16,6 +16,7 @@ require_relative "cli/ci_shard_run_parse"
 require_relative "cli/ci_shard_run_command"
 require_relative "cli/config_command"
 require_relative "cli/default_run"
+require_relative "cli/hooks_command"
 require_relative "cli/help"
 
 module Polyrun
@@ -29,7 +30,7 @@ module Polyrun
     DISPATCH_SUBCOMMAND_NAMES = %w[
       plan prepare merge-coverage report-coverage report-junit report-timing
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
-      run-shards parallel-rspec start build-paths init queue quick
+      run-shards parallel-rspec start build-paths init queue quick hook
     ].freeze
 
     # First argv token that is a normal subcommand (not a path); if argv[0] is not here but looks like paths, run implicit parallel.
@@ -53,6 +54,7 @@ module Polyrun
     include CiShardRunCommand
     include ConfigCommand
     include DefaultRun
+    include HooksCommand
     include Help
 
     def self.run(argv = ARGV)
@@ -177,6 +179,8 @@ module Polyrun
         cmd_queue(argv)
       when "quick"
         cmd_quick(argv)
+      when "hook"
+        cmd_hook(argv, config_path)
       else
         Polyrun::Log.warn "unknown command: #{command}"
         2

data/lib/polyrun/config.rb

@@ -61,6 +61,11 @@ module Polyrun
     def version
       raw["version"] || raw[:version]
     end
+
+    # Optional +hooks:+ block for +run-shards+ / +parallel-rspec+ / +ci-shard-*+ (see {Hooks}).
+    def hooks
+      raw["hooks"] || raw[:hooks] || {}
+    end
   end
 end
 

data/lib/polyrun/hooks/dsl.rb

@@ -0,0 +1,128 @@
+require "monitor"
+
+require_relative "../log"
+
+module Polyrun
+  class Hooks
+    # Ruby DSL for +hooks.ruby+ / +hooks.ruby_file+ in +polyrun.yml+ (see README).
+    #
+    # Example file (+config/polyrun_hooks.rb+):
+    #
+    #   before(:suite) { |env| puts env["POLYRUN_HOOK_PHASE"] }
+    #   after(:each) { |env| }
+    #
+    # Blocks receive a hash with string keys (same env as shell hooks).
+    module Dsl
+      class Registry
+        def initialize
+          @phases = Hash.new { |h, k| h[k] = [] }
+        end
+
+        def add(phase, proc)
+          @phases[phase.to_sym] << proc
+        end
+
+        # @param env [Hash] string-keyed env
+        def run(phase, env)
+          @phases[phase.to_sym].each { |pr| pr.call(env) }
+        end
+
+        def any?(phase)
+          @phases[phase.to_sym].any?
+        end
+
+        def empty?
+          @phases.values.all?(&:empty?)
+        end
+
+        def worker_hooks?
+          any?(:before_worker) || any?(:after_worker)
+        end
+      end
+
+      # Evaluates a hook file with +before+ / +after+ (+before(:suite)+, etc.).
+      class FileContext
+        def initialize(path)
+          @path = path
+          @registry = Registry.new
+        end
+
+        attr_reader :registry
+
+        def load_file
+          instance_eval(File.read(@path), @path)
+          @registry
+        end
+
+        def before(sym, &block)
+          @registry.add(map_before(sym), block)
+        end
+
+        def after(sym, &block)
+          @registry.add(map_after(sym), block)
+        end
+
+        private
+
+        def map_before(sym)
+          case sym.to_sym
+          when :suite then :before_suite
+          when :all then :before_shard
+          when :each then :before_worker
+          else
+            raise ArgumentError, "hooks DSL: before(#{sym.inspect}) — use :suite, :all, or :each"
+          end
+        end
+
+        def map_after(sym)
+          case sym.to_sym
+          when :suite then :after_suite
+          when :all then :after_shard
+          when :each then :after_worker
+          else
+            raise ArgumentError, "hooks DSL: after(#{sym.inspect}) — use :suite, :all, or :each"
+          end
+        end
+      end
+
+      class << self
+        # @return [Registry, nil]
+        def load_registry(path)
+          return nil if path.nil? || path.to_s.strip.empty?
+
+          full = File.expand_path(path.to_s, Dir.pwd)
+          return nil unless File.file?(full)
+
+          mtime = File.mtime(full)
+          cache_mu.synchronize do
+            hit = registry_cache[full]
+            return hit[:registry] if hit && hit[:mtime] == mtime
+
+            reg = FileContext.new(full).load_file
+            registry_cache[full] = {mtime: mtime, registry: reg}
+            reg
+          end
+        rescue => e
+          Polyrun::Log.warn "polyrun hooks: failed to load #{full}: #{e.class}: #{e.message}"
+          nil
+        end
+
+        def clear_cache!
+          cache_mu.synchronize { registry_cache.clear }
+        end
+
+        private
+
+        # rubocop:disable ThreadSafety/ClassInstanceVariable -- single-threaded hook load; Monitor protects cache
+        def cache_mu
+          @cache_mu ||= Monitor.new
+        end
+
+        def registry_cache
+          @registry_cache ||= {}
+        end
+        # rubocop:enable ThreadSafety/ClassInstanceVariable
+      end
+    end
+  end
+end

data/lib/polyrun/hooks/worker_runner.rb

@@ -0,0 +1,27 @@
+require_relative "../log"
+
+module Polyrun
+  class Hooks
+    # Invoked by worker shell wrapper (+ruby -e+). Requires +POLYRUN_HOOKS_RUBY_FILE+.
+    module WorkerRunner
+      module_function
+
+      # @return [Integer] exit code (0 on success)
+      def run!(phase)
+        phase = phase.to_sym
+        path = ENV["POLYRUN_HOOKS_RUBY_FILE"]
+        return 0 if path.nil? || path.empty?
+
+        registry = Dsl.load_registry(path)
+        return 0 if registry.nil? || !registry.any?(phase)
+
+        env = ENV.to_h
+        registry.run(phase, env)
+        0
+      rescue => e
+        Polyrun::Log.warn "polyrun hooks worker #{phase}: #{e.class}: #{e.message}"
+        1
+      end
+    end
+  end
+end

data/lib/polyrun/hooks/worker_shell.rb

@@ -0,0 +1,50 @@
+require "shellwords"
+require "rbconfig"
+
+module Polyrun
+  class Hooks
+    # Builds +sh -c+ script for worker processes (shell + Ruby +before_worker+ / +after_worker+).
+    module WorkerShell
+      # @param cmd [Array<String>] argv before paths
+      # @param paths [Array<String>]
+      # @return [String] shell script body for +sh -c+ (worker process)
+      # rubocop:disable Metrics/AbcSize -- shell + ruby worker hook branches
+      def build_worker_shell_script(cmd, paths)
+        main = Shellwords.join(cmd + paths)
+        rb = RbConfig.ruby
+        bw_shell = commands_for(:before_worker)
+        aw_shell = commands_for(:after_worker)
+        bw_ruby = ruby_registry&.any?(:before_worker)
+        aw_ruby = ruby_registry&.any?(:after_worker)
+
+        lines = []
+        lines << "export POLYRUN_HOOK_PHASE=before_worker"
+        if bw_ruby || bw_shell.any?
+          lines << "set -e"
+          lines << worker_ruby_line(rb, :before_worker) if bw_ruby
+          bw_shell.each { |c| lines << c }
+        end
+        lines << "set +e"
+        lines << main
+        lines << "ec=$?"
+        lines << "export POLYRUN_HOOK_PHASE=after_worker"
+        if aw_ruby || aw_shell.any?
+          lines << "set +e"
+          aw_shell.each { |c| lines << "( #{c} ) || true" }
+          lines << worker_ruby_line(rb, :after_worker, wrap_allow_fail: true) if aw_ruby
+        end
+        lines << "exit $ec"
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def worker_ruby_line(rb_exe, phase, wrap_allow_fail: false)
+        code = %(require "polyrun"; Polyrun::Hooks::WorkerRunner.run!(:#{phase}))
+        line = "#{rb_exe} -e #{Shellwords.escape(code)}"
+        wrap_allow_fail ? "( #{line} ) || true" : line
+      end
+    end
+  end
+end

data/lib/polyrun/hooks.rb

@@ -0,0 +1,185 @@
+require "shellwords"
+
+require_relative "log"
+require_relative "hooks/dsl"
+require_relative "hooks/worker_runner"
+require_relative "hooks/worker_shell"
+
+module Polyrun
+  # Shell and Ruby DSL hooks around parallel orchestration, named like RSpec lifecycle callbacks:
+  # +before_suite+ / +after_suite+ (+before(:suite)+ / +after(:suite)+),
+  # +before_shard+ / +after_shard+ (parent process, per partition index),
+  # +before_worker+ / +after_worker+ (inside each worker process, around the test command).
+  #
+  # Configure under +hooks:+ in +polyrun.yml+: shell strings, and/or +ruby:+ path to a Ruby DSL file.
+  # Run manually: +polyrun hook run <phase>+ (see {CLI}).
+  #
+  # Orchestration respects +POLYRUN_HOOKS_DISABLE=1+ (+run_phase_if_enabled+); +polyrun hook run+ always runs {#run_phase}.
+  class Hooks
+    include WorkerShell
+
+    PHASES = %i[
+      before_suite after_suite
+      before_shard after_shard
+      before_worker after_worker
+    ].freeze
+
+    attr_reader :ruby_file
+
+    def self.disabled?
+      v = ENV["POLYRUN_HOOKS_DISABLE"].to_s.downcase
+      %w[1 true yes].include?(v)
+    end
+
+    # When +POLYRUN_SHARD_TOTAL+ is greater than 1 (+ci-shard-run+ matrix), suite hooks are skipped by default; set
+    # +POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1+ to run +before_suite+ / +after_suite+ on every matrix job (legacy).
+    def self.suite_per_matrix_job?
+      v = ENV["POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB"].to_s.downcase
+      %w[1 true yes].include?(v)
+    end
+
+    def self.from_config(cfg)
+      raw = cfg.respond_to?(:hooks) ? cfg.hooks : {}
+      new(raw.is_a?(Hash) ? raw : {})
+    end
+
+    # Maps CLI or YAML-style names (+before_suite+, +"before(:suite)"+) to a phase symbol or +nil+.
+    def self.parse_phase(str)
+      new({}).send(:canonical_key, str)
+    end
+
+    # @param raw [Hash] +hooks+ block from YAML
+    def initialize(raw)
+      @ruby_file = extract_ruby_file(raw)
+      h = {}
+      raw.each do |k, v|
+        next if %w[ruby ruby_file].include?(k.to_s)
+
+        ck = canonical_key(k)
+        next if ck.nil?
+
+        h[ck] = v
+      end
+      @raw = h.freeze
+      @ruby_registry_loaded = false
+      @ruby_registry = nil
+    end
+
+    def empty?
+      no_shell = PHASES.all? { |p| commands_for(p).empty? }
+      return false unless no_shell
+
+      return true if @ruby_file.nil? || @ruby_file.to_s.strip.empty?
+      return true unless File.file?(File.expand_path(@ruby_file, Dir.pwd))
+
+      reg = ruby_registry
+      reg.nil? || reg.empty?
+    end
+
+    def worker_hooks?
+      return true if commands_for(:before_worker).any? || commands_for(:after_worker).any?
+
+      !!ruby_registry&.worker_hooks?
+    end
+
+    # Merges +POLYRUN_HOOKS_RUBY_FILE+ when a DSL file is configured (for worker +ruby -e+).
+    def merge_worker_ruby_env(env)
+      return env unless @ruby_file
+      abs = File.expand_path(@ruby_file, Dir.pwd)
+      return env unless File.file?(abs)
+
+      env.merge("POLYRUN_HOOKS_RUBY_FILE" => abs)
+    end
+
+    # @param phase [Symbol]
+    # @return [Array<String>]
+    def commands_for(phase)
+      v = @raw[phase.to_sym]
+      case v
+      when nil then []
+      when Array then v.map(&:to_s).map(&:strip).reject(&:empty?)
+      else
+        s = v.to_s.strip
+        s.empty? ? [] : [s]
+      end
+    end
+
+    # Runs Ruby DSL blocks (if any), then shell commands for +phase+.
+    # @return [Integer] exit code (0 if no commands)
+    def run_phase(phase, env)
+      return 0 unless PHASES.include?(phase.to_sym)
+
+      merged = stringify_env_for_hook(env).merge(
+        "POLYRUN_HOOK_PHASE" => phase.to_s,
+        "POLYRUN_HOOK" => "1"
+      )
+
+      reg = ruby_registry
+      if reg&.any?(phase)
+        begin
+          reg.run(phase, merged)
+        rescue => e
+          Polyrun::Log.warn "polyrun hooks: #{phase} ruby hook failed: #{e.class}: #{e.message}"
+          return 1
+        end
+      end
+
+      commands_for(phase).each do |cmd|
+        ok = system(merged, "sh", "-c", cmd)
+        return $?.exitstatus unless ok
+      end
+      0
+    end
+
+    # Like {#run_phase}, but no-ops when {disabled?} (+POLYRUN_HOOKS_DISABLE=1+). Used by run-shards / ci-shard orchestration.
+    def run_phase_if_enabled(phase, env)
+      return 0 if self.class.disabled?
+
+      run_phase(phase, env)
+    end
+
+    private
+
+    def extract_ruby_file(raw)
+      v = raw["ruby"] || raw[:ruby] || raw["ruby_file"] || raw[:ruby_file]
+      return nil if v.nil?
+
+      s = v.to_s.strip
+      s.empty? ? nil : s
+    end
+
+    def ruby_registry
+      return @ruby_registry if @ruby_registry_loaded
+
+      @ruby_registry_loaded = true
+      @ruby_registry = Dsl.load_registry(@ruby_file)
+    end
+
+    def stringify_env_for_hook(env)
+      h = {}
+      env.each { |k, v| h[k.to_s] = v }
+      h
+    end
+
+    # Accept RSpec-style quoted keys from YAML, e.g. +"before(:suite)"+.
+    def canonical_key(k)
+      s = k.to_s.strip
+      sym = if s.match?(/\Abefore\(\s*:suite\s*\)\z/i)
+        :before_suite
+      elsif s.match?(/\Aafter\(\s*:suite\s*\)\z/i)
+        :after_suite
+      elsif s.match?(/\Abefore\(\s*:all\s*\)\z/i)
+        :before_shard
+      elsif s.match?(/\Aafter\(\s*:all\s*\)\z/i)
+        :after_shard
+      elsif s.match?(/\Abefore\(\s*:each\s*\)\z/i)
+        :before_worker
+      elsif s.match?(/\Aafter\(\s*:each\s*\)\z/i)
+        :after_worker
+      else
+        s.downcase.tr("-", "_").to_sym
+      end
+      PHASES.include?(sym) ? sym : nil
+    end
+  end
+end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/lib/polyrun.rb

@@ -25,6 +25,7 @@ require_relative "polyrun/database/shard"
 require_relative "polyrun/database/url_builder"
 require_relative "polyrun/database/provision"
 require_relative "polyrun/database/clone_shards"
+require_relative "polyrun/hooks"
 require_relative "polyrun/env/ci"
 require_relative "polyrun/timing/merge"
 require_relative "polyrun/timing/summary"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -166,6 +166,7 @@ files:
 - docs/SETUP_PROFILE.md
 - lib/polyrun.rb
 - lib/polyrun/cli.rb
+- lib/polyrun/cli/ci_shard_hooks.rb
 - lib/polyrun/cli/ci_shard_run_command.rb
 - lib/polyrun/cli/ci_shard_run_parse.rb
 - lib/polyrun/cli/config_command.rb
@@ -176,6 +177,7 @@ files:
 - lib/polyrun/cli/env_commands.rb
 - lib/polyrun/cli/help.rb
 - lib/polyrun/cli/helpers.rb
+- lib/polyrun/cli/hooks_command.rb
 - lib/polyrun/cli/init_command.rb
 - lib/polyrun/cli/plan_command.rb
 - lib/polyrun/cli/prepare_command.rb
@@ -184,6 +186,7 @@ files:
 - lib/polyrun/cli/quick_command.rb
 - lib/polyrun/cli/report_commands.rb
 - lib/polyrun/cli/run_shards_command.rb
+- lib/polyrun/cli/run_shards_parallel_children.rb
 - lib/polyrun/cli/run_shards_plan_boot_phases.rb
 - lib/polyrun/cli/run_shards_plan_options.rb
 - lib/polyrun/cli/run_shards_planning.rb
@@ -225,6 +228,10 @@ files:
 - lib/polyrun/database/url_builder/template_prepare.rb
 - lib/polyrun/debug.rb
 - lib/polyrun/env/ci.rb
+- lib/polyrun/hooks.rb
+- lib/polyrun/hooks/dsl.rb
+- lib/polyrun/hooks/worker_runner.rb
+- lib/polyrun/hooks/worker_shell.rb
 - lib/polyrun/log.rb
 - lib/polyrun/minitest.rb
 - lib/polyrun/partition/constraints.rb