feat(plan): saturated pools cut to measured parallelism (#14 phase 2)

[sylvesterdamgaard]

Completes #14. Phase 1 (#17) covered the histogram's blind spots with an aggregate CPU shape - but only in the report; cpuCeilingFor, the ceiling the allocator uses, still required per-request readings and stayed 0 for sub-50 ms workloads.

The design (after a live lesson): aggregateFill is the ONE place that reads the tick-delta aggregate, with a regime rule:

• Calm host → the share (cores per busy worker) is honest; fill follows from per-worker cost, like the per-request path.
• CPU-saturated host → the share is poisoned (every queued worker reads 'busy': 25 workers on 2 cores read share 5%, fill 40, ceiling 80) and fill IS the measured cores - tick deltas cannot be inflated by workers that only wait. ceil(1.9 cores) × headroom 2.0 = 4.

Both the allocator and the report call it, so every kind of round produces the same number. The first cut of this PR had the cores rule only in the starved-gate block and the share fallback in cpuCeilingFor - live, those two flapped against each other every other round (queue drained for one scrape → ceiling 80 → regrow toward memory's 30 → starved round → cut to 4 → SIGUSR2 reload per flip), collapsing throughput from 391 to ~110 rps. The flap round is now a regression test.

Safety:

• Cut gated on --cpu AND the Trusted baseline (a cap below the configured ceiling IS a cut; cuts are opt-in). Without the flag: phase-1 hold, report shows what --cpu would do (SaturationMeasured).
• A pool only claims the cores reading when it drives ≥ half the box: an io-shaped pool on a host made busy by a neighbor falls through to the share, whose fill is large and non-binding, exactly as io should be (regression-tested).
• Aggregate not yet trusted (< MinAggCPURounds): hold, never cut on an unproven signal.

Live evidence (2 CPUs, 16→24-worker static pool, sub-3ms CPU flood, embedded in cbox-init):

phase	workers	rps
pre-trust plateau (30 min)	24	~305
cut fires	4	368 → 380 → 391 (+28%)
(first cut of the PR: flap)	4↔25	collapsed to ~110 - the bug this revision removes

A fresh 45-minute run with the regime rule is queued; expect the cut to hold at 4 with ~390 rps to the end - numbers land as a comment.

Tests: oversized-starved pool converges to 4 (CPUBound); flap round holds at 4; io-neighbor not capped; untrusted aggregate holds; no-flag holds; saturated cpuCeilingFor returns 4 where the poisoned share said 80. Full gate green.

[sylvesterdamgaard]

Live proof, third and final run (2 CPUs / 1 GiB, 16→24-worker static pool, sub-3ms CPU flood via wrk -t2 -c32, embedded in cbox-init, 60s measurement windows, quiet host):

windows	workers	rps
1-30 (pre-trust plateau)	24	~318
31 (trust lands, cut fires)	24 → 4	338
32-46 (steady state)	4	392-398, fifteen consecutive windows

One Pool resized event in the entire run. +25% throughput.

The three runs tell the whole story:

1. Run 1 (first cut of this PR): the cut fired (+28%) but the share-based ceiling in the queue-drained rounds said 80 while the starved rounds said 4 → flap 4↔25 with a SIGUSR2 reload per flip, collapsing throughput to ~110 rps. Became the flap-round regression test.
2. Run 2 (regime rule, 0.5× threshold): the cut never fired - measured cores DEFLATE under host contention (a co-located build left the container ~1.15 effective cores of its 2-CPU quota, a hair under the threshold). Became the 0.35× calibration + the agg_cores/agg_busy/saturation_measured log instrumentation, so this is never undiagnosable again.
3. Run 3 (this revision): cut at the trust point, stable to the end.

Worker-sweep cross-check: the sweep measured 396-400 rps at 2-4 workers and ~305 at 20+ on this endpoint - the tuner now lands exactly on the measured optimum, from live evidence only.