[finding] `os dev --port` is unvalidated and `os start --port` is unbounded — both forward to the `serve` child on a channel that renames the operator's input

[os-litant]

Filed unassigned and ungraded by the #12662 dev, session session_01UjujZN219uFzBhSYfMykCd, while adding port-input validation to os serve. ⛔ Not graded, not routed. Out of scope for #12662, which repairs serve — this is about the two commands that spawn it.

Measured, on origin/main at 9a2f3dfe4

Three separate facts, all in the same seam.

1. os dev --port has no validation at all. packages/cli/src/commands/dev.ts:76:

port: Flags.string({ char: 'p', description: 'Server port (overrides $PORT)' }),

2. os start --port is an integer flag with no bounds. packages/cli/src/commands/start.ts:81:

port: Flags.integer({ char: 'p', description: 'Port to listen on (overrides $PORT, default 3000)' }),

Flags.integer without min/max accepts 99999 and -1 — measured against this repo's @oclif/core 4.13.3. Those values reach the child.

3. Both rename the input on the way to the child, so serve's refusal names a channel rather than what the operator typed.

• dev.ts:389-409 builds the child argv as ['serve', '--dev', ...(port ? ['--port', port] : [])], and port is flags.port ?? readEnvWithDeprecation('OS_PORT', 'PORT') (dev.ts:387). So PORT=abc os dev reaches the child as --port abc: serve refuses it naming --port, which the operator never typed.
• start.ts:337 puts ...(flags.port ? { PORT: String(flags.port) } : {}) into the child env. So os start --port 99999 reaches the child as PORT=99999: serve refuses it naming PORT, when the operator typed --port.

Since #12662 the child does refuse these values legibly instead of dying on a raw ERR_SOCKET_BAD_PORT — so this is a naming inaccuracy in a message that exists to be accurate, not a crash. It is documented as a known limit in formatInvalidPortNotice's docblock rather than papered over.

Not established here

• Severity not judged. No claim about how often either spelling is used.
• ⚠️ Whether the repair is per-command validation (each parent refuses in its own vocabulary, before spawning), or passing provenance to the child, or leaving it as-is because the child's message is already a large improvement, is not decided here. Note that per-command validation on os dev would inherit the same accept-set question [finding] os serve --port abc is never validated — parseInt yields NaN and the boot dies on a raw ERR_SOCKET_BAD_PORT #12662 raised (see the sibling finding filed alongside this one).
• ⛔ Whether os start --port should carry min/max is the cheapest piece and is still not decided here: it duplicates the bound that now lives in serve.ts, and a second copy of a range is what [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 and [finding] os serve --port abc is never validated — parseInt yields NaN and the boot dies on a raw ERR_SOCKET_BAD_PORT #12662 both went out of their way to avoid.

Re-check

git grep -n "port: Flags" origin/main -- packages/cli/src/commands/dev.ts packages/cli/src/commands/start.ts
git grep -n "PORT: String(flags.port)" origin/main -- packages/cli/src/commands/start.ts
git grep -n "'--port', port" origin/main -- packages/cli/src/commands/dev.ts

Dedup

Searched the port family: the open card is #12662 (this finding's parent); #12543, #12620, #12525, #12526, #12548, #12441, #11113, #11669 are all closed and all about port conflict, contention or the arg separator, not about the two parent commands' own flag validation. No match.

Generated by Claude Code

[os-litant]

Triage: needs-user-decision + domain:cli, type Task。分诊座位 session session_01JQBYgAZ3misb64snPnqu2b,2026-08-27 增量轮,since 锚 2026-08-27T06:40:24Z。

改判说明:落地时误挂 pm:blocked(正文与评论均无 Blocked-by: 行,半标注)+ finding(已具备复现命令与三点测量,不再是待定级观察),两者摘除;卡片自身三次写「⛔ not decided here」,是修复路径未定的契约选择卡,不是待定级 finding,也不是等外部解锁,直接入决策箱。与 #12674(同一 #12662 dev 同批留下的兄弟 finding,已判 queue/Task:只加提示、不动接受集)同源但不同形——#12674 是纯静默修复,本卡三点里有两点(os dev --port 补校验、os start --port 补边界)是收紧已发布命令的接受集,落在人工地板。

四维分析:

• 实际业务需求:三点里第③点(错误消息指错了参数名/环境变量名)是真实可撞到的体验缺陷——用户输入被 dev/start 转发给 serve 子进程时改名,serve 拒绝时报的是子进程收到的名字而非用户敲的名字,排障时会被误导。第①②点(补校验/加边界)目前只是理论对齐,[finding] os serve --port abc is never validated — parseInt yields NaN and the boot dies on a raw ERR_SOCKET_BAD_PORT #12662/[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 两次裁决都刻意没有把这类边界复制到第二个入口,没有证据显示这曾经真的绊倒过用户。
• 项目长远合理性:让 dev/start/serve 三个入口对同一个 --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/[finding] os serve --port abc is never validated — parseInt yields NaN and the boot dies on a raw ERR_SOCKET_BAD_PORT #12662 明确绕开的形状(避免散落的第二份契约)。更长远的路线是「provenance 传递」——子进程报错时带上原始入口的参数名——但那是更大的重构,不是本卡能顺手做的。
• 防 AI 写代码犯错:错误消息指错参数名本身就是一种「AI/人类都会被误导」的缺陷,修复它是收紧诚实度、不是放宽;而补校验/加边界如果做,必须给出显式 FROM/TO 变更单与 changeset,不能被当作静默清理夹带过去——这正是需要人工裁决而非代裁的原因。
• 创业阶段不扩散需求:两个未验证过是否有真实用户撞到的校验点,不应该在没有推动力的情况下抢先补齐;先做消息命名修复(低成本、无契约变化),把接受集收紧留给真正被用户报告后再裁。

选项:

• A(推荐):只修第③点——dev/start 转发参数给 serve 子进程时,让 serve 的拒绝消息报告原始入口的参数名/环境变量名(如 --port vs PORT),不新增任何校验、不动 dev/start 的接受集。与 [finding] os serve --port 3e3 silently binds port 3 — parseInt's tolerance means a port can be accepted as a value the operator never named #12674 同批同修法,S 级、机械、无争议。
• B:额外给 os dev --port 补齐与 os serve 一致的校验、给 os start --port 补 min/max 边界——收紧两个已发布命令的接受集,需要显式 FROM/TO 变更单 + changeset,且需回答是否在 serve.ts 之外再放一份范围常量([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/[finding] os serve --port abc is never validated — parseInt yields NaN and the boot dies on a raw ERR_SOCKET_BAD_PORT #12662 曾主动避免)。
• C:维持现状,仅记录不修复——错误消息指错参数名的体验缺陷会继续存在。

---

Generated by Claude Code