Two port-reservation registries now run the same protocol in different directories — converge sdui_pick_free_port and smoke_pick_free_port onto one helper

Filed unassigned by the dev seat working #10212. Not a defect today — recorded so the
duplication is a deliberate state rather than an accident. Duplicate search first
(quoted "port-reservations", "PORT_RESERVATION_DIR", "pick_free_port", plus a
semantic search for registry convergence): no hits other than #10167/#10212 themselves.

What is on `main` now

Two shell helpers run a byte-identical claim-before-probe protocol against two
different directories:

	`sdui_pick_free_port`	`smoke_pick_free_port`
script	`scripts/gen-sdui-manifest.sh`	`scripts/publish-smoke.sh`
registry	`${TMPDIR:-/tmp}/sdui-port-reservations`	`${TMPDIR:-/tmp}/objectstack-port-reservations`
override	`SDUI_PORT_RESERVATION_DIR`	`SMOKE_PORT_RESERVATION_DIR`
base port	5180	3210
probe	`probe.listen(port, '127.0.0.1')`	`probe.listen(port)` (wildcard)

Landed by #10217 (#10167) and the #10212 PR respectively. Normalising the names and
diffing the two node programs shows the on-disk format and every algorithm — O_EXCL
claim, release-on-probe-failure, sweep floor/ceiling, pid liveness, flock around the
sweep only — is identical; the only differences are the registry directory and the
probe address.

Why it was left this way rather than merged in the #10212 PR

The two draw from disjoint ranges — [3210, 3410) and [5180, 5380) — so they
cannot hand each other the same port. Sharing one directory buys nothing measurable
today; it only starts to matter if a caller ever passes an overlapping base.
The probe address difference is load-bearing in both directions and must survive
any merge: the smoke script probes the wildcard address deliberately, because that is
the spelling serve.ts's own isPortAvailable() uses, so it sees a busy port exactly
when the CLI would. The sdui helper probes loopback because that is what vite binds.
A shared helper needs the probe address as a parameter, not a constant.
Doing it inside smoke_pick_free_port in scripts/publish-smoke.sh is the same TOCTOU probe as #10167 — concurrent callers scanning from 3210 are all handed 3210 #10212 would have meant editing scripts/gen-sdui-manifest.sh and its
collision test, both outside that card's declared file surface, hours after fix(devx): reserve the port sdui_pick_free_port hands out, instead of probing and letting go #10217
landed there.

What converging would look like

One helper — probably sourced from a small scripts/lib/ file both scripts read — taking
base, span and the probe address, against a single neutral registry. The
objectstack-port-reservations directory name was chosen in #10212 expressly so that
convergence is a pure rename on the sdui side, with no on-disk format change and no
migration: existing claim files stay valid.

⚠️ Whoever takes this should keep the two collision tests' contention assertions
(CONCURRENT_DISTINCT, TRIPLE_DISTINCT, and the STEAL_CLAIM_ON_PICK positive
control) running against the real shared registry rather than an overridden scratch
one — the point of those is that they measure the registry actual callers use.

Generated by Claude Code

test(spec): let the publish-smoke THIEF own the port it calls held (o…

Hold made legal — a real trigger existed, it was just never written down

devx lane PM, session session_01PfaSTikked61BkcsB5Rn69, round 13. Authorization: maintainer instruction this session to clear the eight illegal pm:on-hold cards flagged by half-state patrol H9.

This card was held with no Restart-when: in either channel, which makes the hold illegal — nothing could ever wake it. Unlike the two closed in this sweep, this one has a genuine, checkable trigger; it simply was never recorded. Adding it rather than closing.

Restart-when: the two port registries can hand out the same port — i.e. the reserved
  ranges of sdui_pick_free_port and smoke_pick_free_port intersect. One-line predicate:
  the [base, base+span) ranges in scripts/gen-sdui-manifest.sh and scripts/publish-smoke.sh
  overlap, OR either script stops passing its own registry directory.
Restart-touch: scripts/gen-sdui-manifest.sh, scripts/publish-smoke.sh

Verified false today, so the hold is live rather than already-fired — read off origin/main, not recalled:

	sdui	smoke
base port	5180	3210
registry	`sdui-port-reservations`	`objectstack-port-reservations`

Ranges [5180, 5380) and [3210, 3410) remain disjoint, so the two cannot hand each other the same port and convergence still buys nothing measurable. That is precisely the card's own argument for leaving it, and it is now a predicate instead of a paragraph.

⭐ Why this is a hold and not a close: the duplication is deliberate and already paid for. objectstack-port-reservations was named neutrally in #10212 expressly so convergence stays a pure rename on the sdui side — no on-disk format change, no migration, existing claim files stay valid. That prepared work is worth keeping alive.

⚠️ Carried forward for whoever wakes it, because it is the part a naive merge would destroy: the probe address difference is load-bearing in both directions. The smoke script probes the wildcard address deliberately, because that is the spelling serve.ts's own isPortAvailable() uses, so it sees a busy port exactly when the CLI would; the sdui helper probes loopback because that is what vite binds. A shared helper needs the probe address as a parameter, not a constant. And keep the contention assertions (CONCURRENT_DISTINCT, TRIPLE_DISTINCT, STEAL_CLAIM_ON_PICK) running against the real shared registry, not an overridden scratch one — measuring the registry actual callers use is the whole point of those tests.

Generated by Claude Code

关 `not_planned` —— 维护者逐张复核 on-hold 卡时同意关闭;纯开发工具卡

分诊席(session_01Tw7jnJinGHvoGSi8aFkhPJ),2026-09-23T09:05Z。维护者 2026-09-23 在分诊会话里逐张复核 pm:on-hold 卡,对第五组的回复原文:「10164 不考虑旧的;11182 当前版本就优先处理,统一为cel;其他同意」。本卡在那一组里的建议是关闭。

呈给维护者的事实

两个开发脚本(scripts/gen-sdui-manifest.sh 的 sdui_pick_free_port 和 scripts/publish-smoke.sh 的 smoke_pick_free_port)各有一份相同的「预留空闲端口」协议,注册目录不同。端口范围 [5180, 5380) 和 [3210, 3410) 不重叠,两者不会分出同一个端口;合并它们今天带不来任何可测的好处(卡面原话)。
为以后合并做的准备(中性的注册目录名,探测地址必须作为参数传入)都记在正文里。
本卡是 tooling,对产品没有影响。SKILL.md:374:产品仓的 P0/P1 开着时,没有解锁对象的 p2/p3 tooling 卡一律关闭。

卡面的测量和设计笔记原样保留;重开是免费的。

关闭理由:not_planned,同时摘掉 pm:on-hold。

Generated by Claude Code

Navigation Menu

Repository navigation

Two port-reservation registries now run the same protocol in different directories — converge `sdui_pick_free_port` and `smoke_pick_free_port` onto one helper #10261

What is on `main` now

Why it was left this way rather than merged in the #10212 PR

What converging would look like

Hold made legal — a real trigger existed, it was just never written down

关 `not_planned` —— 维护者逐张复核 on-hold 卡时同意关闭;纯开发工具卡

呈给维护者的事实

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Two port-reservation registries now run the same protocol in different directories — converge sdui_pick_free_port and smoke_pick_free_port onto one helper #10261

Description

What is on main now

Why it was left this way rather than merged in the #10212 PR

What converging would look like

Activity

os-zhuang commented on Aug 27, 2026

Hold made legal — a real trigger existed, it was just never written down

objectstack-fleet commented on Sep 23, 2026

关 not_planned —— 维护者逐张复核 on-hold 卡时同意关闭;纯开发工具卡

呈给维护者的事实

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Two port-reservation registries now run the same protocol in different directories — converge `sdui_pick_free_port` and `smoke_pick_free_port` onto one helper #10261

What is on `main` now

关 `not_planned` —— 维护者逐张复核 on-hold 卡时同意关闭;纯开发工具卡