test(multi-processes-execution): hoist iteration cap to the Fake (global guard)

The previous commit kept the iteration cap inside one anonymous fake used by
the new adversarial test only. That doesn't kill Infection's six timed-out
mutants on this class because the OTHER preexisting tests in the file run
against the same mutant first, hang (their MultiProcessesExecutionFake has
no cap), and Infection kills the entire PHPUnit process at its 120s limit
before the new test ever gets a chance to fail cleanly.

Hoisting the hasPendingWork() override to MultiProcessesExecutionFake makes
EVERY test in the file inherit the 200-iteration cap implicitly. Verified by
applying the M14 mutation (addProcessToQueue removed): all 40 tests in
MultiProcessesExecutionTest now fail with the cap-exceeded diagnostic in
~12s instead of hanging until the 120s timeout. Infection will record those
six mutants as Killed rather than Timed Out on the next run, with a
precise pointer to the run-loop regression.

Test simplified accordingly — the anonymous subclass goes away, the test
uses the shared Fake directly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Test

tests/Doubles/MultiProcessesExecutionFake.php

@@ -9,4 +9,47 @@
 class MultiProcessesExecutionFake extends MultiProcessesExecution
 {
     use ExecutionFakeTrait;
+
+    /**
+     * @var int Iterations of the do-while observed by hasPendingWork(). Public
+     *          so tests can inspect or reset it.
+     */
+    public int $iterations = 0;
+
+    /**
+     * @var int Hard cap on do-while iterations. Set generously for the suite
+     *          (each iteration polls O(numTools) processes; six tools converge
+     *          in ≲12 iterations). Override per-test if a stress scenario
+     *          legitimately needs more.
+     */
+    public int $iterationCap = 200;
+
+    /**
+     * Liveness guard against deadlock regressions in runProcesses(). Without
+     * this cap the do-while spins indefinitely when a guard-protecting branch
+     * is removed (addProcessToQueue, finishExecution, the catch blocks, the
+     * hasPendingWork early-exit), and Infection has to wait its 120s timeout
+     * before recording the mutant as TIMED_OUT.
+     *
+     * Throwing here escapes to the OUTER `catch (Throwable)` on line 55 of
+     * MultiProcessesExecution::runProcesses() (the inner catch on line 51
+     * cannot snare it because the while condition is evaluated outside the
+     * inner try/catch). The outer handler registers it as a 'General' error
+     * so callers can detect the cap was hit. The bundled
+     * `run_loop_terminates_under_adversarial_inputs` test asserts the absence
+     * of that key for the contract; existing tests benefit from the cap
+     * implicitly — instead of a 120s hang on regressed code they fail fast
+     * with a clear diagnostic and Infection records a kill rather than a
+     * timeout.
+     */
+    protected function hasPendingWork(int $totalProcesses): bool
+    {
+        if (++$this->iterations > $this->iterationCap) {
+            throw new \Error(
+                "MultiProcessesExecution::runProcesses() did not converge after {$this->iterations} iterations — "
+                    . 'check addProcessToQueue, finishExecution and the catch blocks for guard regressions.'
+            );
+        }
+        return parent::hasPendingWork($totalProcesses);
+    }
 }

tests/Unit/Tools/Execution/MultiProcessesExecutionTest.php

@@ -474,23 +474,20 @@ function failFast_takes_priority_over_ignoreErrorsOnExit()
     /**
      * Run-loop liveness invariant: under any combination of success / failure /
      * timeout / fail-fast / ignore-errors flags, MultiProcessesExecution::runProcesses()
-     * MUST terminate within a bounded number of iterations. The previous tests
-     * assert the OUTCOME (errors collected, skipped tools, etc.) but none of
-     * them have an iteration cap — a mutation that removes addProcessToQueue,
-     * flips hasPendingWork, or breaks the catch blocks lets the do-while spin
-     * forever, and the test suite would hang up to PHPUnit's wall-clock budget
-     * (>120s under Infection — already reported as timed-out mutants on lines
-     * 38-41 and 131-134 of the production class).
+     * MUST terminate within a bounded number of iterations. None of the previous
+     * outcome-asserting tests guard against a divergent loop — a mutation that
+     * removes addProcessToQueue, flips hasPendingWork, or breaks the catch
+     * blocks lets the do-while spin forever (>120s under Infection, reported
+     * as timed-out mutants on lines 38-41 and 131-134 of the production class).
      *
-     * SIGALRM is NOT a viable guard here because the inner `catch (Throwable)`
-     * on line 51 of runProcesses() catches the AssertionFailedError thrown by
-     * `$this->fail()` and the loop just keeps spinning. Instead we override
-     * `hasPendingWork()` (the do-while condition, evaluated OUTSIDE the inner
-     * try/catch) and throw an `\Error` once iterations exceed a sane cap.
-     * The error escapes to the outer `catch (Throwable)` on line 55, which
-     * registers it as a 'General' error in the returned Errors. The test then
-     * asserts the 'General' key is absent — present means the cap was hit and
-     * the run loop did not converge.
+     * The cap lives in MultiProcessesExecutionFake::hasPendingWork() so EVERY
+     * test in this file inherits it implicitly. Without that, this single
+     * adversarial test would still time out alongside the others when run
+     * against a divergent mutant — Infection kills the entire PHPUnit process
+     * on the first hang, ignoring any test that would have failed cleanly.
+     * With the cap on the Fake, divergent mutants surface as a 'General' error
+     * inside the returned Errors object (see the Fake's docblock for why);
+     * this test asserts the absence of that key.
      *
      * @test
      * @dataProvider adversarialRunLoopScenarios
@@ -519,22 +516,7 @@ function run_loop_terminates_under_adversarial_inputs(string $scenario, array $c
         $tools = $this->toolsFactory->__invoke($configurationFile->getToolsConfiguration());
 
         $printerMock = Mock::spy(Printer::class);
-        $multiProcessExecution = new class ($printerMock, new GitStagerFake()) extends MultiProcessesExecutionFake {
-            /** @var int Iterations of the do-while in runProcesses() observed by hasPendingWork */
-            public int $iterations = 0;
-            public int $iterationCap = 200;
-
-            protected function hasPendingWork(int $totalProcesses): bool
-            {
-                if (++$this->iterations > $this->iterationCap) {
-                    throw new \Error(
-                        "MultiProcessesExecution::runProcesses() did not converge after {$this->iterations} iterations — "
-                            . 'check addProcessToQueue, finishExecution and the catch blocks for guard regressions.'
-                    );
-                }
-                return parent::hasPendingWork($totalProcesses);
-            }
-        };
+        $multiProcessExecution = new MultiProcessesExecutionFake($printerMock, new GitStagerFake());
 
         if (!empty($config['failedTools'])) {
             $multiProcessExecution->failedToolsByFoundedErrors($config['failedTools']);