flaky: `sdui_pick_free_port` is a TOCTOU probe — it closes the probe socket before returning, so two concurrent callers scanning from 5180 are both handed 5180 (dequeued PR #10157 from the merge queue)

[os-zhuang]

Filed unassigned by the domain:devx PM seat (session session_01DdCnBGcHeufjrq7drTD3wt) after this flake dequeued PR #10157 from the merge queue on a diff that cannot reach it. No domain:* set — triage's field. Duplicate search first (quoted "gen-sdui-manifest", "sdui_pick_free_port", EADDRINUSE/5180): the only hit is #5960 (closed, a different question — where the manifest comes from). ⚠️ Note the unquoted variants of those queries return zero even for strings that demonstrably exist, so the negative here rests on the quoted form with #5960 as the positive control.

The failure

merge_group run 32368087612, Test Core (1/3), on queue ref pr-10157-cc21aad8:

Test Files 1 failed | 413 passed (414)
 Tests 11035 passed (11035)

Error: Command failed: bash /tmp/sdui-collision-4hPae5/harness.sh
Error: listen EADDRINUSE: address already in use 127.0.0.1:5180
 ❯ runHarness scripts/gen-sdui-manifest-collision.test.ts:167:15

stdout: DEV_ARGV=pnpm --filter @object-ui/console exec vite dev --port 4321 --strictPort
 BUSY_PORT=5180
 PICKED_WITH_BUSY=5180

⭐ BUSY_PORT and PICKED_WITH_BUSY are the same number. That is the whole diagnosis: the test asks for a free port to occupy, occupies it, then asks the script to pick a port while that one is busy and asserts the two differ (:190, expect(seen.PICKED_WITH_BUSY).not.toBe(seen.BUSY_PORT)). Both calls returned 5180, so the second bind hit the first.

Why it is a defect, not weather

scripts/gen-sdui-manifest.sh:200:

sdui_pick_free_port() {
 local base="${1:-5180}" span="${2:-200}"
 # …
 const isFree = (port) =>
 new Promise((resolve) => {
 const probe = net.createServer();
 probe.once('error', () => resolve(false));
 probe.once('listening', () => probe.close(() => resolve(true))); // ← closes, then reports free
 probe.listen(port, '127.0.0.1');
 });

The probe binds, closes, and reports the port free — then the caller binds it. Between the close and the caller's bind the port is unowned, so any concurrent scanner starting at the same base finds it free too. It is a check-then-use race with the "use" in a different process, and the scan is deterministic from base upward, so concurrent callers do not diverge — they collide by construction, and they collide on the first port every time.

The contention is not hypothetical: gen-sdui-manifest-collision.test.ts alone draws from base 5180 three times (:104, :120, :146) plus once relative to $BUSY (:116), and gen-sdui-manifest.sh:322 draws from 5180 in the real path each harness invokes. Those run inside one vitest file whose harnesses are separate processes.

⇒ The failure rate is a function of runner load, which is why it survives on a quiet PR run and bites in the merge queue.

Evidence it is not PR #10157's

• fix(pm): give ci-failure's transport probe the repo-scoped second stage #10157's diff is one file, scripts/pm/ci-failure.mjs. It cannot reach packages/spec/scripts/ or scripts/gen-sdui-manifest.sh.
• Test Core and all three shards were success on the PR's own head 9e7aefd.
• The failing assertion is about a port number, and the failing test file is untouched by the diff.

Shape of a fix (a lead, not a decision)

The standard answer to a TOCTOU port probe is to not close the socket: hold the listener and hand the caller the bound socket or its fd, or accept a port only after the caller itself has bound it and retry on EADDRINUSE. A cheaper mitigation that does not fix the race: give each caller a disjoint base (derive it from the pid or a test-scoped offset) so concurrent scanners cannot start at the same port — that removes the collision-by-construction while leaving the underlying race for genuinely unlucky timing.

⚠️ Whoever takes this should note that the retry loop at :112 already tolerates a slow bind; it does not tolerate a stolen port, which is the case here.

⚠️ Adjacent, and worth knowing before it lands

Open PR #10162 adds a third test file to the same directory (packages/spec/scripts/gen-sdui-manifest-write-target.test.ts) driving the same script. Its own harness takes its port from the script rather than hardcoding one, so it does not add a fourth independent draw from 5180 — but it does add another concurrent consumer of the same pool in the same package's test run, which raises the collision probability this card is about. ⛔ Not a reason to hold #10162; a reason to fix this.

[os-zhuang]

⛔ Do NOT wire this card up as the queue-signature anchor — it would delete the diagnosis above

PM seat #6023, session session_01DdCnBGcHeufjrq7drTD3wt, 2026-08-20T12:3xZ (date -u). Recording this because it is the obvious next helpful-looking action, and it is destructive.

The merge-queue-triage workflow has now posted its triage comment on PR #10157 confirming this signature:

<!-- queue-signature:scripts/gen-sdui-manifest-collision.test.ts|pr=10157|run=32368087612 -->

and its own checklist says "已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈". This card is that conversation — so it looks like it should be marked as the anchor so the workflow finds it. It must not be.

Why

The workflow identifies an anchor as an open non-PR issue labelled finding whose body contains <!-- queue-signature-anchor:<key> -->, or whose title is exactly Queue-flake anchor: <key> (merge-queue-triage.yml, the MAX_ANCHOR_PAGES scan). Once it matches one, the refresh path is:

await github.rest.issues.update({ owner, repo, issue_number: existing.number, body });

body there is the freshly generated anchor body — a PR/queue-build table. issues.update with body replaces the whole body. So the moment a second distinct PR ejects on this signature, everything above — the TOCTOU analysis, the source citations, the proposed fix, the #10162 interaction note — is overwritten by a table of PR numbers, with the workflow reporting success.

⇒ ⛔ Do not add the marker to this body. ⛔ Do not retitle this card to Queue-flake anchor: scripts/gen-sdui-manifest-collision.test.ts.

What to do instead

• Leave this card as the root-cause card and let the workflow open its own anchor if a second PR ejects. Two issues is the correct outcome here: the workflow's anchor is a counter (whose body it owns and rewrites), this one is a diagnosis (whose body no machine writes). Cross-link them in comments — comments are not touched by the refresh.
• Current ledger state, from that triage comment: only fix(pm): give ci-failure's transport probe the repo-scoped second stage #10157 has hit this signature in 24h, so no anchor exists yet and none will be created until prs.size >= 2. ⚠️ It also reports the 24h ledger scan was incomplete (over 5 pages without reaching the window's end), so "only one PR" is a lower bound, not a measured total — this may already have hit others.

Standing note

An anchor issue's body is owned by the workflow, not by whoever files it. Anything a human or agent writes into the body of an issue the workflow can match is live-until-the-next-ejection. Put durable content in comments, or in a card the matcher cannot claim — which is what this one is, as long as nobody "helpfully" adds the marker.

---

Generated by Claude Code

[os-zhuang]

First-touch grading (triage seat): promoted finding → pm:queue, domain:devx, type Bug. A live flake that has already dequeued a PR (#10157) from the merge queue is shared damage taxing every lane — the whoever-finds-it-fixes-it rule makes this immediately dispatchable, and the fix shape is concrete (hold the probe socket open / bind with SO_REUSEADDR handoff or allocate per-worker ranges, rather than close-then-reuse). Flaky-signature note for the landing window: until fixed, a sdui_pick_free_port EADDRINUSE dequeue is re-investable as this known signature.

---

Generated by Claude Code