fix: per-worker test-port bands so the mutation gate stops crash-scoring (D-033)

[nzneit]

Closes the mutation gate's port-collision nondeterminism (D-033), the open intake item from #19.

The bug, reproduced rather than theorized

Two concurrent bun test processes over one port-heavy file collide: run A passes 68/68, run B dies with EADDRINUSE after a single test. The CI mutation gate runs Stryker at --concurrency 4, so its workers hit this constantly — Failed to start server. Is port 19001 in use? appears throughout #19's job log. A crashed run is scored as a KILLED mutant, so the gate was nondeterministic in both directions and flipped a required check both ways on that PR: three mutants were "killed" with an empty killedBy (crash luck), while a genuinely killable one survived on CI's filesystem.

The fix: kernel-arbitrated sentinel bands

Every port the suite binds in [11800, 19999] now goes through port(base) / portStr(base). Each test process claims a band at preload time by binding a sentinel socket on 127.0.0.1:(11700 + band) — arbitration lives in the kernel's port table, so it needs no cooperation, survives crash/respawn, and works for plain concurrent bun test too, not just Stryker.

Band 0 is the identity map: port(19010) === 19010, so an ordinary local run binds exactly the literals in the source and every debugging habit still works. Bands ≥ 1 relocate each distinct base into a compact 512-wide window.

Why not the alternatives (both rejected with reasons, in D-033)

• Arithmetic worker-id bands. Stryker forks workers with env: { STRYKER_MUTATOR_WORKER: workerId, ...process.env } — the spread comes after, so a parent env carrying that variable collapses all four workers into one band silently. The id is also a monotonic spawn counter, not a slot index, so any modulus is pigeonhole-doomed.
• Serialize the gate (--concurrency 1). Measured at ~4x wall time on a path already past the 15-minute job timeout, and it does nothing for the local collision reproduced above. Kept as the documented fallback.

Geometry, and why these numbers

The binding constraint is the Linux ephemeral source-port floor (32768): a band port at or above it can be stolen by a kernel-assigned ephemeral port, reintroducing the exact flake. The top band's last port is 20480 + 23*512 + 511 = 32767. macOS's ephemeral range starts at 49152, so satisfying Linux satisfies macOS with 16k to spare. A dense lazy index is required rather than a modular map — measured over the real port set, mod 512 leaves 29 colliding residues, mod 2048 still leaves 8.

Portability (macOS/BSD)

The sentinel must bind an explicit 127.0.0.1 and never set reusePort: listeners set SO_REUSEADDR by default, and BSD then permits two live binds on one port when the bound addresses differ, where Linux refuses. Deleting the host argument keeps every test green on Linux, so it is pinned at the source level. No Linux-only interface is read at runtime; the claim-failure hint offers both ss and lsof commands.

Bands arbitrate our own processes only — they cannot stop a third party holding a base port (Expo defaults to 19000/19001, which this suite allocates), so OFFBOOK_TEST_BAND=<0..24> forces a band, and the failure message names it.

The orphan rule: probe-and-skip, never a reaper

The sentinel is a process claim, not a port claim. When a mutant run is SIGKILLed on timeout, the OS frees the sentinel but any detached offbook up server it spawned keeps holding that band's ports. So a band is kept only when its sentinel binds and a bind-probe finds that band's spawned-server ports free; otherwise the sentinel is released and the scan moves on. Never a kill: an in-run reaper at concurrency > 1 would SIGKILL sibling workers' live runs, scoring their mutants KILLED — a silent drift toward false green, strictly worse than the EADDRINUSE it replaces.

Enforcement

test/port-hygiene.test.ts makes the scheme a fact rather than a convention: totality (no raw in-window literal anywhere), base accounting, band math, the portability pins, orphan-list completeness, and preload load order. Every gate was proved with a planted violation observed red and then removed — including the shapes that defeated the first draft: a literal declared in a test body, a test.each table, 19_010, 0x4a3a, and arithmetic on a port() result.

One thing the gate then surfaced (not caused by this branch)

With the sibling test files changed, the gate's changed-file selection pulls runfile.ts into scope on its own for the first time — and 11 mutants survived in probeServer. They are pre-existing test gaps, not sweep damage: the runfile.test.ts diff is purely mechanical (every removed line has a port()-wrapped replacement, zero assertion changes), and the mutants decode to the retry semantics — nothing proved the retry happens after a silent first answer, nothing proved it does not happen after a good one, nothing measured its doubled budget — plus an identity shape check no body ever exercised one field at a time. Earlier campaigns always mutated all four modules together, where other coverage masked them; the one test that did kill the shape mutant spawns the CLI as a child process, and child coverage never returns to Stryker, so perTest attribution could never select it.

Fixed with three in-process tests. All seven mutant families were hand-applied and each now dies.

Verification

• Full gate set by exit code: biome 0, typecheck 0, check-docs 0, bun test 0 — 733 pass / 0 fail.
• Gate replica at --concurrency 4 (the exact failing condition): pass, score 100.00 — 370 killed, 0 survived, 27 ignored.
• The original repro harness, 4-way: 4/4 runs 68 pass / 0 fail, zero EADDRINUSE (before: one passed, the rest died).
• Two independent adversarial audits (desync lens, guarantee lens) over the 20-file sweep: no desyncs; 12 simultaneous claimers took 12 distinct bands. Their 14 findings are all fixed in this branch.