fix(pool): clamp pool top-up to runners_maximum_count

[jeff-french]

Description

runners_maximum_count was enforced only by the scale-up lambda. The pool lambda (adjustPool) had no knowledge of the maximum and topped up purely against pool_size, so a warm pool could drive the total number of runners far past runners_maximum_count.

calculatePooSize() counts only idle runners. Under a sustained burst of queued jobs, runners created to fill the pool are immediately picked up and become busy, so they stop counting toward numberOfRunnersInPool. Every scheduled pool cycle therefore sees ~0 idle runners and launches another full pool_size batch — with no upper bound — while the scale-up lambda correctly refuses to launch ("maximum number of runners reached"). The two lambdas actively disagree about the cap.

Fixes #5186.

Changes

• lambdas/.../pool/pool.ts — read RUNNERS_MAXIMUM_COUNT (default -1 = unlimited, matching scale-up semantics) and clamp topUp to the remaining headroom under the cap. ec2runners already contains every running runner for the type (busy + idle), so its length is the current total — no extra API call. Logs when the cap limits the top-up.
• Terraform — thread the value into the pool lambda's environment:
  • modules/runners/pool/main.tf: RUNNERS_MAXIMUM_COUNT = var.config.runners_maximum_count
  • modules/runners/pool/variables.tf: add runners_maximum_count to the config object
  • modules/runners/pool.tf: runners_maximum_count = var.runners_maximum_count
  • modules/runners/pool/README.md: regenerated docs

Backward compatibility

Defaulting the env to -1 preserves current behavior when it is unset and matches the documented "-1 disables the maximum check" semantics.

Relationship to #5062

#5062 added Math.max(0, …) in scale-up to stop a negative TotalTargetCapacity reaching CreateFleet when currentRunners already exceeds maximumRunners. That guards the crash symptom; this PR addresses the root cause of how currentRunners exceeds maximumRunners (the pool creating past the cap). The two are complementary.

Tests

pool.test.ts adds cap coverage: at-max ⇒ 0 created, over-max ⇒ 0, headroom-clamped ⇒ 2, within-headroom ⇒ pool-driven, and -1 ⇒ unlimited. The base RUNNERS_MAXIMUM_COUNT in the suite is set to -1 so the existing pool-logic tests remain cap-free.

• control-plane vitest suite: 499 passed
• eslint / prettier --check: clean
• terraform validate / terraform fmt: clean

🤖 Generated with Claude Code