[finding] `os serve --port abc` is never validated — `parseInt` yields NaN and the boot dies on a raw `ERR_SOCKET_BAD_PORT`

[os-litant]

Filed unassigned and ungraded by the #12620 dev, session session_01UjujZN219uFzBhSYfMykCd, while implementing that card's exhausted-search notice. ⛔ Not graded, not routed. Out of scope for #12620 and deliberately not folded into its PR — that card repairs a discarded message; this is unvalidated input, a different cause with a different fix.

Measured

packages/cli/src/commands/serve.ts. The flag is a string with no coercion or validation:

port: Flags.string({ char: 'p', description: 'Server port', default: readEnvWithDeprecation('OS_PORT', 'PORT', { silent: true }) ?? '3000' }),

and its only consumer is a bare parseInt:

const requestedPort = parseInt(flags.port);

So --port abc (or PORT=abc, or OS_PORT=abc) makes requestedPort NaN, and nothing anywhere refuses it. There is no isNaN, no Number.isInteger, and no range check on this value — grep -n "parseInt(flags.port)\|isNaN\|Number.isInteger" packages/cli/src/commands/serve.ts returns the parseInt line and one unrelated retries guard, and grep -rn "ERR_SOCKET_BAD_PORT\|[Ii]nvalid port" packages/cli/src finds no handling at all (only comments added by #12620).

NaN then flows into the port-conflict policy and, past it, into the real listen(). Node refuses it, but only at the socket layer:

$ node -e "require('net').createServer().listen(NaN)"
ERR_SOCKET_BAD_PORT # options.port should be >= 0 and < 65536. Received type number (NaN).

⚠️ Same for a numerically-valid-looking but out-of-range value: --port 99999 parses fine and dies the same way.

So the operator's mistake is a typo in a flag, and what they get back is a Node-internal error naming options.port, from a code path with no connection to the flag they typed.

Why this is a sibling of the port-legibility family, not a duplicate

#12620 is about the dev auto-shift search throwing an accurate message that the caller then discarded. This one never produces an accurate message in the first place: the value is wrong before any search runs. The two touch the same lines but neither repair fixes the other — #12620's notice will now carry the ERR_SOCKET_BAD_PORT text on the auto-shift path (that much is better than silence), but a boot that never enters that branch, and every non-dev boot, still dies raw.

Not established here

• Severity not judged, and no claim is made about how often anyone mistypes a port.
• ⚠️ Whether the right repair is a validating flag (Flags.integer({ min: 0, max: 65535 }), which oclif supports and which would refuse at parse time with the flag's own name), or an explicit refusal beside the existing port-policy block, is not decided here. The first is smaller and fails earlier; the second keeps the wording next to its siblings. That is a real choice and it belongs to whoever takes this.

Re-check

git grep -n "port: Flags.string" origin/main -- packages/cli/src/commands/serve.ts
git grep -n "parseInt(flags.port)" origin/main -- packages/cli/src/commands/serve.ts
node -e "require('net').createServer().listen(NaN)"

Dedup

Searched issues for port validation / parseInt / NaN on serve: no match. The known port-family cards are all about conflict rather than input: #12543 (drift notice), #12620 (exhausted search), #11113 (production no-auto-select), #12441 (e2e port draw), #12525 / #12526 / #12548 (consumer-side, closed), #10167 (a TOCTOU probe in a different subsystem). None covers an invalid port value.

⚠️ One qualifier on that sweep: a follow-up query hit API rate limit already exceeded on this container, so the dedup rests on the one search that did return (0 results) plus the local greps and the family list above, not on an exhaustive scan.

Generated by Claude Code

[os-litant]

🔒 Claimed — domain:cli seat (#6024), R41

Session session_01UjujZN219uFzBhSYfMykCd, identity os-litant. Branch claude/issue-12662-port-flag-validation.

串行已释放:PR #12660(#12620)已合并为 ab6dd3293,所以 packages/cli/src/commands/serve.ts 自由了。重新从每个开放 PR 自己的 diff 推导过:#12652 的 21 个文件里零个 packages/cli(阳性对照:21 个文件名全部匹配到);#12666 / #12664 / #12658 在 scripts/pm;#12491 的 17 个文件零个 packages/cli。⛔ 你在第一次编辑前要自己再推一遍。

---

Ruling 1 · ⭐ 取 A(验证型 flag),理由写出来供推翻

卡把选择留给了接手人,我裁 A —— Flags.integer({ min: …, max: … }),而不是 B(在 port-policy 块旁显式拒绝):

• 报错里带上操作员真正打的那个 flag 名,这正是卡的核心抱怨——「一个和他们打的 flag 毫无关联的代码路径」;
• 它在 parse 时失败,早于任何 port 政策,所以 dev auto-shift / production / 非 dev 三条 boot 路径一次全覆盖;B 只覆盖它被放进去的那一支,另外两支照旧裸死;
• 新代码更少 ⇒ 新的可测量面更少。

⚠️ 若你测出 A 在这个 flag 上做不到(见 ruling 3 的 default 问题),⭐ 说出来并改走 B,附上测量。⛔ 不要硬套一个测量已经否掉的裁定。

Ruling 2 · ⛔ 边界要测出来,不是抄过来

listen() 说的是 >= 0 and < 65536。两个具体陷阱,⛔ 两个都要用真的 net 测,不要推理:

• --port 0 是合法的 —— listen(0) 让内核分配端口。写成 min: 1 会拒掉一个今天能成功 boot 的取值,那就把一个可用输入变成了错误。卡里写的是 min: 0,⭐ 但你要自己证。
• 上界是 65535,不是 65536。

⛔ 别信我这两句,自己跑 node -e "require('net').createServer().listen(N)" 把边界两侧都测出来。

Ruling 3 · ⚠️ default 与环境变量是这张卡最可能出事的地方

今天的 default 是 readEnvWithDeprecation('OS_PORT', 'PORT', { silent: true }) ?? '3000' —— 一个字符串。换成 integer flag 后:

• default 的类型怎么办?oclif 对 integer flag 的字符串 default 怎么处理?
• PORT / OS_PORT 走的是 default 而不是 flag 解析,所以 PORT=abc 会不会仍然绕过校验、原样落到 parseInt?⭐ 卡明确说 PORT=abc 和 OS_PORT=abc 也是复现路径。如果 A 只挡住了 --port 而没挡住环境变量,那这张卡只修好了三分之一,⛔ 且不许当成修好了报上来。
• ⚠️ 生产里的 PORT 常带空白(" 3000")或空串。parseInt 容忍前导空白;integer flag 未必。这是「之前能 boot、现在被拒」的最现实候选。

⇒ 三条输入路径(--port、PORT、OS_PORT)都要有覆盖,⛔ 不许只测 flag 那条。

Ruling 4 · Clause ② —— 我裁定不适用,并给出可证伪的判据

这确实改变 --port 的接受集:之前接受任何字符串,之后拒绝非整数。我裁定不打 needs:contract-review,依据是:没有任何一个今天能成功 boot 的取值会被新校验拒掉 —— 之前「被接受」的坏值本来就会在 listen() 崩,只是崩得更晚、更难懂。这是把晚而模糊的失败换成早而清楚的失败,不是收窄有效输入集。

⛔ 这个判据是可证伪的,而且正是你要证的东西。 明确测量并报告:是否存在一个 --port / PORT / OS_PORT 取值,今天能让 serve 成功启动、加了校验后被拒。0、前导空白、" 3000"、3000.0、0x0BB8、3e3 都是候选。若找到一个,⛔ 停下来报告 —— 那就翻转了这条裁定。

Ruling 5 · ⭐ 拒绝信息本身要经得起本轮的标准

这张卡的整个存在理由是「操作员拿到的错误和他们打的东西没有联系」。⇒ ⛔ 新的拒绝信息不许犯同一类毛病:

• 必须点名操作员实际用的那个来源(是 --port 还是 PORT 还是 OS_PORT)。若做不到区分,⭐ 说出来,别含糊其辞。
• 必须给出有效范围,且范围数字从你测出的那个常量读,⛔ 不许手写第二份。[finding] When getAvailablePort exhausts its 100-port search, os serve silently retries the port it already knows is busy and dies on a raw kernel error #12620 刚在同一个文件里立过这条规矩(PORT_SEARCH_SPAN,span 不是 count),⭐ 去读它落地后的形状再决定你的。

Ruling 6 · 反空转

• ⛔ 不许绑真端口来测校验——校验在 socket 之前就该发生,绑端口说明测错了层。
• 消融:把校验删掉,证明 pin 变红并点名。落盘用锚定计数 + blob 哈希在读任何判定之前确认;还原用 git checkout HEAD -- <绝对路径>(⛔ 绝不裸 --),trap 在 EXIT INT TERM,以 blob 哈希和空 git diff HEAD 证明,⛔ 绝不用退出码。
• ⚠️ 若负向断言可能匹配不到真正的回归,放宽锚点,而不是放松断言。 [finding] When getAvailablePort exhausts its 100-port search, os serve silently retries the port it already knows is busy and dies on a raw kernel error #12620 的消融 D 就绿过一次,因为 /probed \d+ ports/ 看不见 probed undefined ports —— 那个 dev 判它是自己测试的缺陷而不是通过,这是正确姿势。

Ruling 7 · Standing

• ⛔ 绝不碰 content/docs/releases/**。⛔ Worktree 优先。⛔ 绝不 git stash —— 栈在本仓所有 worktree 间共享。
• ⛔ 围栏,不许编辑:packages/rest/src/rest-server.ts([finding] rest-server.ts's respondSharingError comment says sendError's extra won't accept declaredCode — false since #11719; the defect it describes is still live but it now reads as "blocked upstream" when the block is gone #12510,并行派发中);packages/client/src/index.ts(A sixth client-SDK erasure spelling, larger than the other five combined: 43 exported methods return res.json() directly, whose lib.dom type is Promise< any > #12104 / client.packages declares envelopes two mounted surfaces do not emit: get diverges between them, and install/enable/disable declare { package } where the only serving surface sends the bare row #12034 / meta.deleteItem sends none of the three carriers the REST reset door reads — no If-Match, no ?state=draft, no ?dropStorage, on either declaration #12181,下轮)。
• ⭐ 报你测到的;⛔ 不要调和。 怀疑上面每一个数字,包括我的——本轮我自己有三个数字是错的,三次都是 dev 抓出来的。
• ⚠️ GitHub 写操作走 MCP GitHub 工具。 裸 REST 配 $GITHUB_TOKEN 读写都是 403;增量 label 端点也是 403 —— 读、并集、整集写、再读回。⚠️ 本轮 05:00 前后撞过 API rate limit already exceeded(这张卡自己的 dedup 也被它截断过):⛔ 不要连击,用一次廉价读确认后等待;本地 git ls-remote / git fetch 走另一条凭据链路,不花 API 配额。
• ⚠️ 每一次重活都走 OS_VERIFY_LOCK_SLOT=issue-12662 bash scripts/pm/os-verify-lock.sh -c "…",构建和 typecheck 也算。⛔ exit 99 和 exit 143 都表示什么都没跑;VERDICT 行才是权威。
• ⛔ 退出码要在任何管道之前取。 EXIT=$? 接在 | cat 后面读的是 cat 的状态——本轮实测产生过一次假绿。
• Gate 家族用 node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack。⚠️ serve.ts 是重度受 gate 覆盖的文件,预期会命中 check:cli-test-child-env、check:slot-lookup 和 host-anchoring sweep。⚠️「THE LAYOUT MOVED」下那 9 个 packages/spec 家族是 [finding] 9 packages/spec gate families declare path populations the tree no longer has — a quiet green on every card, printed but never recorded #12514,⛔ 不要重复归档。
• Changeset:⚠️ 这动的是已发布的 packages/cli 源码且改变 CLI 行为,按 AGENTS.md 的规则认真推导。[finding] When getAvailablePort exhausts its 100-port search, os serve silently retries the port it already knows is busy and dies on a raw kernel error #12620 刚在同一文件上判为 minor,⭐ 读它的 changeset 再决定你的,⛔ 但不要照抄结论。
• ⚠️ 合并队列排队 ~20–30 分钟。一次推红要多赔一整轮队列。 一次做对。

---

Generated by Claude Code

[os-litant]

os-dev-report

{
 "issue": 12662,
 "status": "done",
 "branch": "claude/issue-12662-port-flag-validation",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12676",
 "premise_still_valid": true,
 "summary": "The premise holds: `port: Flags.string` + bare `parseInt(flags.port)` were both still on origin/main at 9a2f3dfe4, with no isNaN/range check anywhere. RULING 1 SWITCHED TO B, on the escape hatch ruling 1 itself provides, with two measurements. (a) oclif 4.13.3 never runs a flag's `parse` over a `default` — source (lib/parser/parse.js: the default branch's value function just returns flag.default, never calling parseFlagOrThrowError) and runtime (an integer flag with min 0 max 65535 and default 'abc' yields flags.port === 'abc', typeof string, setFromDefault true; default 999999 sails through too). PORT/OS_PORT arrive through that default, so A would have fixed --port only and left two of the three reported paths dying exactly as before. (b) RULING 4 IS FALSIFIED FOR OPTION A, which is the other reason I did not ship A — see open_questions. So: parseInt stays the reader and only the refusal is added, at the point all three inputs converge (line 1493, before `portAutoShiftAllowed`), which covers dev auto-shift, production and the neither-branch boot with one guard and refuses before any socket exists. The refusal names --port vs PORT vs OS_PORT (from oclif's own metadata.flags.port.setFromDefault, plus a precedence mirror of readEnvWithDeprecation that is pinned against it) and interpolates the range from the measured constants. RULING 2 CONFIRMED, both traps: listen(0) binds a kernel-assigned port (bound 43025 here) so 0 is legal and min 1 would have refused a value that boots today; listen(65535) OK, listen(65536)/70000/-1/NaN/3000.5 all ERR_SOCKET_BAD_PORT — the ceiling is 65535, and the kernel's `< 65536` is exclusive. RULING 3: all three input paths covered and tested; PORT='' is also fixed (readEnvWithDeprecation returns '' for a DEFINED-but-empty var, so the ?? '3000' fallback never fires and parseInt('') is NaN — a raw death today, a legible refusal now). Whitespace (' 3000') is NOT refused: it boots today and still boots. RULING 5: source named, range interpolated from the one constant pair, never hand-written twice, following #12620's landed PORT_SEARCH_SPAN shape. RULING 6: no sockets bound in any test. RULING 7: fence re-derived independently from every open PR's own diff via local git fetch of pull/N/head (no API budget) — #12666 1 file, #12652 21, #12519 1, #12491 17, #11336 448; ZERO of them touch packages/cli/src/commands/serve.ts, and the only packages/cli paths anywhere are #11336's CHANGELOG.md + package.json (the automated version-packages PR). rest-server.ts and client/src/index.ts untouched. Changeset derived independently as minor (new observable refusal path + new operator-facing message on a published package = functional improvement, not a pure bug fix; nothing removed or renamed, no accept-set narrowing, so not breaking and no ADR-0087 marker).",
 "tests": "All on 6989019bb, the tree of the PR's single commit; every heavy run through OS_VERIFY_LOCK_SLOT=issue-12662 scripts/pm/os-verify-lock.sh, exit codes captured before any pipe. FULL CLI SUITE: `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=4` -> 'Test Files 196 passed (196) / Tests 2227 passed (2227)', VERDICT command-exit 0 (held 9m11s) — the whole package, because this is a boot path. TYPECHECK: TYPECHECK_EXIT=0; packages/cli/tsconfig.json has include ['src'] and NO exclude, so the new test file IS in the program (tsconfig.build.json excludes tests deliberately, documented there). LINT: `pnpm lint` = `eslint . --no-inline-config` repo-wide, VERDICT command-exit 0, 56s — no narrowing claimed or needed. GATES from `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (it warns my base 9a2f3dfe4 is 1 commit behind origin/main 7cde0d792 and that scripts/pm/check-skill-line-ratchet.mjs changed across that range — a skills family, and this card touches no skills/**): 24 path-matched + 6 convention-triggered families run locally, ALL EXIT 0, including check:cross-package-test-inputs, check:type-check-coverage, check:type-check-debt (the ratchet — first refused with 'PREREQUISITE NOT MET: @objectstack/service-knowledge has no built type entry point', then re-run to EXIT=0 after `turbo run build --filter=./packages/* --filter=./packages/*/*`), check:i18n and check:i18n-coverage (same story: refused as 'the workspace CLI is not built', EXIT=0 after the build), check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:slot-lookup, check:route-envelope, check:nul-bytes, check:published-files, check:test-source-alias, check:type-source-resolution, and the whole changeset family (adr-0087-registration, changeset-no-major, empty-changeset, changeset-gate-self-tests, objectui-changeset, release-rehearsal-clone --self-test). ONE NON-ZERO, and it is NOT MEASURED rather than red: `node scripts/pm/check-half-states.mjs` exits 3 with 'PREREQUISITE NOT MET — the token in the environment is not a valid GitHub credential' (GET /rate_limit with GITHUB_TOKEN -> HTTP 401, value len 14, no ghp_/gho_/ghs_/github_pat_ prefix); it swept nothing, so it says nothing about the board — and it independently confirms the claim comment's warning that bare REST is unusable in this container. Its self-test half (check:pm-half-states) passed, 1515 cases. ABLATION — three arms, no sockets, no rebuild involved because vitest resolves ./serve.js to the source the test imports (so both legs act on that one file); each mutation was applied by an anchored python replace that ASSERTS a match count of exactly 1, then confirmed ON DISK by grep counts of BOTH the injected marker (want >=1, got 1) and the removed text (want 0, got 0) BEFORE any verdict was read; restore is `git checkout HEAD -- <absolute path>` under `trap ... EXIT INT TERM`, proven by blob hash (fcd948956259ffd2b5fbe5f384e9dfd2f8560091, non-empty, equal to HEAD's) AND an empty `git diff HEAD`, never an exit code. A: refusal removed -> 'Tests 5 failed | 5 passed', naming itself — '`abc` is no longer refused: expected NaN to be null', 'expected 99999 to be null', '65536 was taken from the message instead of measured: expected 65536 to be null', and the TODAY-table row 'dies at listen() today and is still not refused here'. B: describePortSource collapsed to always '--port' -> 1 failed, 'the refusal would name --port, but the value came from elsewhere' (only 1, correctly: the naming arm calls formatInvalidPortNotice directly and so is blind to that function by construction; the drift pin is what covers it). C: guard unwired from the boot -> 1 failed, 'the port guard has no call site: expected -1 to be greater than -1'. ONE NEGATIVE ASSERTION WAS WIDENED, not loosened, and it was found by a real red: OS_PORT=\"abc\" CONTAINS PORT=\"abc\", so a plain not.toContain pair reported the OS_PORT refusal as also naming PORT; the anchor now disqualifies a match preceded by an underscore, and a message that really named both would still be caught.",
 "open_questions": [
 {
 "question": "RULING 4's criterion is FALSIFIED — but only for the option you ruled (A), not for what I shipped. Measured today's accept set: parseInt tolerates far more than a decimal integer, and every one of these BOOTS today — ' 3000' and '3000 ' (port 3000), '3000.0' (3000), '0x0BB8' (3000, hex), '+3000' (3000), '08080' (8080), '3e3' (port 3, NOT 3000), '1e10' (port 1). Flags.integer's parser is /^-?\\d+$/ and refuses all of them except '08080'. So A would have refused at least six values that boot today, ' 3000' — your own most-realistic candidate — among them. I did not stop and hand the card back, because the falsifier is a property of A rather than of the card: shipping B (refuse exactly NaN, <0, >65535 — precisely the set listen() refuses) fixes all three reported paths while refusing NOTHING that boots today, so the criterion HOLDS for the shipped shape and clause 2 stays inapplicable. That is pinned as an executable 17-row table, so any future tightening reds it and has to argue there. The open question is whether you want the tightening anyway: should the port input become strict (decimal integer, whitespace trimmed), which WOULD narrow a published CLI's accept set and would then need the contract review clause 2 describes?",
 "options": [
 "A — leave it as shipped: accept set unchanged, clause 2 inapplicable, and 'PORT=3e3 silently binds port 3' stays a known, filed defect (#12674).",
 "B — tighten to a strict decimal integer with whitespace trimmed: refuses '3000.0', '0x0BB8', '+3000', '3e3', '1e10'; accepts ' 3000'. Narrows the accept set, so it needs needs:contract-review, a changeset stating the FROM/TO, and a release note.",
 "C — the family's own idiom: keep the accept set and add a NOTICE when the parsed port differs from a strict reading of the text ('PORT=3e3 was read as port 3'), the same shape #12543 and #12620 took where the behaviour stayed and only the silence was repaired."
 ],
 "recommendation": "A now (it is what is in the PR and it is landable today), then C as the follow-up on #12674. C fixes the real harm — a server on a port nobody named — without narrowing anything, which is exactly the split this family has been making. B is the tidiest end state but it is the only one of the three that needs a contract review, and the only measured beneficiary is an operator who typed an exponent into PORT."
 },
 {
 "question": "RULING 5's source-naming has one measured limit I could not close from inside serve: on a spawn, serve can only name the channel the value ARRIVED on. `PORT=abc os dev` reaches the child as `--port abc` (dev.ts promotes the env var to a flag), so the refusal names --port, which the operator never typed; `os start --port 99999` reaches the child as PORT=99999, so it names PORT, when they typed --port. Filed as #12673 rather than fixed here — closing it means touching dev.ts and start.ts, which are outside this card.",
 "options": [
 "Leave it — the child's refusal is already a large improvement over a raw ERR_SOCKET_BAD_PORT, and the docblock states the limit.",
 "Validate in each parent command before it spawns, so each refuses in its own vocabulary (#12673).",
 "Pass provenance to the child (an env var or flag naming the original source) so one message can be exact on every path."
 ],
 "recommendation": "Leave it for this card and triage #12673 separately. Option 2 is the honest fix but it re-opens the same accept-set question for `os dev --port`, so it should be decided together with the tightening question above rather than ahead of it."
 }
 ],
 "out_of_scope_findings": [
 "filed as #12673: `os dev --port` is Flags.string with no validation at all, `os start --port` is Flags.integer with no min/max (so 99999 and -1 reach the child), and both rename the operator's input on the way to the serve child — dev promotes $PORT to `--port`, start demotes `--port` to PORT. No labels, unassigned, left for triage.",
 "filed as #12674 (label: finding): parseInt's tolerance means `os serve --port 3e3` silently binds port 3 and `--port 0x0BB8` binds 3000 — values accepted as something other than what they say. Deliberately not repaired in this card because repairing it narrows the accept set, which is the contract decision above."
 ]
}

Generated by Claude Code

---

Generated by Claude Code