Context
The #15783 measurement proved a ~2.7× unit-suite wall-clock win at --workers=4 but the probe (PR #15784) closed unmerged because parallelism exposed test-isolation defects. #15789 (SortZone global bleed) and #15790 (profiling budgets) were the named enablers. This ticket is a third isolation defect that surfaces under --workers=N: the genesisProbe child-spawning tests collide on ephemeral ports.
Scope correction (2026-07-24T20:xx): this ticket was originally filed bundling three observed --workers=4 failures (port / Body-Brain purity / contention-timeout). On verification that over-scoped it: the purity and timeout failures were measured on a branch without the port fix, and have not been confirmed independent of the port collision — they may be cascade, may be environmental, may be real. Rather than assert three defects from one measurement, this ticket is narrowed to the port collision (the one root-caused and fixed); the other two are re-measured post-merge (Post-Merge Validation below) and filed only if they reproduce with the port fix in place. Narrowing to match the committed fix (8fdd54dfb9) and the original branch intent (fix/15847-workers-port-isolation).
The Problem
Under --workers=N, genesisProbe.spec.mjs's child-spawning tests fail with test Neural Link Bridge exited before opening port 5xxxx (1) — a different port each run (49420, 50315, 53657 observed). The production findFreePort helper binds an ephemeral port, closes it, and returns the number; the spawned Bridge child binds it a moment later. That allocate → close → hand-off gap is a TOCTOU: two workers' ephemeral draws can land on the same just-freed port, and the second child to bind it exits EADDRINUSE. Single-worker ordering (CI today, workers: 1) masks it entirely — genesisProbe passes on dev in CI; it fails only under parallel workers.
The Architectural Reality
Playwright reuses a worker process across spec files and runs each worker's tests serially. The fix is not to make the collision rarer (retry, wider ephemeral range) but unrepresentable: give each worker a disjoint port band, so no two workers can ever hand the same number to a child, and a worker's own serial ordering means it never races itself.
test/playwright/unit/ai/scripts/diagnostics/genesisProbe.spec.mjs — two child-spawn sites (the waitForChildReady missing-child test and the standalone Bridge binds the AiConfig-owned non-default port test) call the ephemeral findFreePort.
The Fix
Already committed (8fdd54dfb9 on fix/15847-workers-port-isolation): a worker-isolated findFreeWorkerPort() that probes only within [20000 + workerIndex*1000, +1000), replacing findFreePort at both child-spawn sites. The lone remaining listen(0) (the readiness test's own server, never handed to a child) is correctly untouched — it has no hand-off window.
Acceptance Criteria
Out of Scope
- Profiling wall-clock budgets — #15790.
- The
workers: process.env.CI ? 4 re-land flip + ≥2 green samples — that AC lives on #15790.
- Body/Brain purity ordering (
chromaProcess.spec.mjs) and the contention timeout — observed under --workers=4 on the port-fix-less branch but NOT confirmed independent; re-measured post-merge, filed separately only if they reproduce.
Post-Merge Validation
Related
#15783 (measurement, closed) · #15789 (SortZone bleed, closed) · #15790 (profiling budgets + the re-land AC) · #15798 (Local Runtime Parity epic).
Origin Session ID: e8b8a230-b55f-4d39-acb2-8680bc922399
Retrieval Hint: query_raw_memories("genesisProbe worker-isolated port band findFreeWorkerPort TOCTOU") · fix commit 8fdd54dfb9.
Context
The #15783 measurement proved a ~2.7× unit-suite wall-clock win at
--workers=4but the probe (PR #15784) closed unmerged because parallelism exposed test-isolation defects. #15789 (SortZone global bleed) and #15790 (profiling budgets) were the named enablers. This ticket is a third isolation defect that surfaces under--workers=N: thegenesisProbechild-spawning tests collide on ephemeral ports.Scope correction (2026-07-24T20:xx): this ticket was originally filed bundling three observed
--workers=4failures (port / Body-Brain purity / contention-timeout). On verification that over-scoped it: the purity and timeout failures were measured on a branch without the port fix, and have not been confirmed independent of the port collision — they may be cascade, may be environmental, may be real. Rather than assert three defects from one measurement, this ticket is narrowed to the port collision (the one root-caused and fixed); the other two are re-measured post-merge (Post-Merge Validation below) and filed only if they reproduce with the port fix in place. Narrowing to match the committed fix (8fdd54dfb9) and the original branch intent (fix/15847-workers-port-isolation).The Problem
Under
--workers=N,genesisProbe.spec.mjs's child-spawning tests fail withtest Neural Link Bridge exited before opening port 5xxxx (1)— a different port each run (49420, 50315, 53657 observed). The productionfindFreePorthelper binds an ephemeral port, closes it, and returns the number; the spawned Bridge child binds it a moment later. That allocate → close → hand-off gap is a TOCTOU: two workers' ephemeral draws can land on the same just-freed port, and the second child to bind it exitsEADDRINUSE. Single-worker ordering (CI today,workers: 1) masks it entirely — genesisProbe passes ondevin CI; it fails only under parallel workers.The Architectural Reality
Playwright reuses a worker process across spec files and runs each worker's tests serially. The fix is not to make the collision rarer (retry, wider ephemeral range) but unrepresentable: give each worker a disjoint port band, so no two workers can ever hand the same number to a child, and a worker's own serial ordering means it never races itself.
test/playwright/unit/ai/scripts/diagnostics/genesisProbe.spec.mjs— two child-spawn sites (thewaitForChildReadymissing-child test and thestandalone Bridge binds the AiConfig-owned non-default porttest) call the ephemeralfindFreePort.The Fix
Already committed (
8fdd54dfb9onfix/15847-workers-port-isolation): a worker-isolatedfindFreeWorkerPort()that probes only within[20000 + workerIndex*1000, +1000), replacingfindFreePortat both child-spawn sites. The lone remaininglisten(0)(the readiness test's own server, never handed to a child) is correctly untouched — it has no hand-off window.Acceptance Criteria
genesisProbechild-spawn sites allocate from a disjoint per-worker band;findFreePortis no longer imported by the spec. (8fdd54dfb9)--workers=1(non-regression) — the existing green single-worker path is preserved.--workers=Nre-land, since the collision is non-deterministic and cannot be reliably reproduced red locally, and this worktree cannot boot the Bridge child at all (environmental).Out of Scope
workers: process.env.CI ? 4re-land flip + ≥2 green samples — that AC lives on #15790.chromaProcess.spec.mjs) and the contention timeout — observed under--workers=4on the port-fix-less branch but NOT confirmed independent; re-measured post-merge, filed separately only if they reproduce.Post-Merge Validation
--workers=4 --retries=2with this fix on dev. IfchromaProcesspurity and/or the contention timeout still fail hard (unexpected), file each as its own root-caused ticket. If they were port-collision cascade, they clear with this fix — which is why they were NOT pre-filed as confirmed defects.Related
#15783 (measurement, closed) · #15789 (SortZone bleed, closed) · #15790 (profiling budgets + the re-land AC) · #15798 (Local Runtime Parity epic).
Origin Session ID: e8b8a230-b55f-4d39-acb2-8680bc922399
Retrieval Hint:
query_raw_memories("genesisProbe worker-isolated port band findFreeWorkerPort TOCTOU")· fix commit8fdd54dfb9.