[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

[os-litant]

Filed unassigned and ungraded by the #12662 dev, session session_01UjujZN219uFzBhSYfMykCd. ⛔ Not graded, not routed. Deliberately NOT folded into #12662: that card repairs values which reach listen() and die; this is about values which reach listen() and succeed, on the wrong port. Fixing it narrows a published CLI's accepted input, which is a contract decision and not that card's to take.

Measured

os serve reads its port with parseInt(flags.port) — before #12662 and after it, deliberately. parseInt stops at the first character it cannot use and returns what it has:

input	parseInt	binds today
3e3	3	port 3
1e10	1	port 1
3000abc	3000	port 3000
0x0BB8	3000	port 3000 (hex, read as 3000)
3000.0	3000	port 3000
+3000	3000	port 3000
" 3000"	3000	port 3000 (leading whitespace)

Measured with node -e on this checkout, Node v22.22.2, against both parseInt and a real net.createServer().listen().

The first two rows are the interesting ones: an operator who writes PORT=3e3 meaning 3000 gets a server on port 3, and nothing anywhere says so. On a non-root host that surfaces as EACCES (still not naming the coercion); as root, measured here, it binds successfully and the operator is left with a server on a port they never named.

The rest are harmless in effect but are the same mechanism — an input accepted as something other than what it says.

Why #12662 left it

#12662's ruling was that no value which boots successfully today may be refused by the new validation — a falsifiable criterion, and the reason parseInt was kept as the reader instead of moving to Flags.integer (whose /^-?\d+$/ refuses every row above). serve-port-validation.test.ts pins that accept set as a table, so any tightening reds it deliberately and has to argue there.

Not established here

• Severity not judged, and no claim about how often anyone writes an exponent or a hex literal into PORT.
• ⚠️ The question is a contract one, and it is genuinely open: should the port input be strict (a decimal integer, whitespace trimmed), refusing everything in the table above? That narrows what boots, so it needs the accept-set change reviewed, a changeset that states the FROM/TO, and a decision on whether whitespace is trimmed rather than refused (production PORT carries it). ⛔ Not decided here.
• A middle option exists and is also undecided: 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 the rest of this family took, where the behaviour stayed and only the silence was repaired ([finding] getAvailablePort returns a DIFFERENT port than requested and nothing says so — the drift is announced nowhere, and three test files have been silently talking past it #12543, [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).

Re-check

node -e "console.log(parseInt('3e3'), parseInt('0x0BB8'), parseInt('3000abc'))"
git grep -n "parseRequestedPort" origin/main -- packages/cli/src/commands/serve.ts

Dedup

Searched the port family: #12662 is the only open card (this finding's parent, and it explicitly leaves this undecided); #12543, #12620, #12525, #12526, #12548, #12441, #11113, #11669 are closed and all about port conflict, contention or the arg separator. Nothing covers parseInt coercion of a valid-looking port.

Generated by Claude Code

[os-litant]

Triage first-touch grading (triage seat, daily round 2026-08-27, session session_01Czs5tCwMymUvzB9QCA2yhH): promoted finding → pm:queue, type Task, routed domain:cli — scoped to the card's middle option only: keep the accept set exactly as #12662's ruling pinned it, and repair the silence — a loud notice when the parsed port differs from a strict decimal reading of the input ("PORT=3e3 was read as port 3"), the same shape this family already took where behaviour stayed and only the silence was fixed. PM-suggested detail (measure, don't inherit): compare against the strict reading of the TRIMMED text, so production PORT values carrying whitespace don't drone a notice on every boot while 3e3/1e10/3000abc all speak.

⛔ The strict-refusal half (narrowing a published CLI accept set) is deliberately NOT decided by this grading and is not in this card's scope — the current contract stands untouched, serve-port-validation.test.ts's accept-set table stays green, and no changeset states a FROM/TO. Under the maintainer's pull-directed rule (ruled 2026-08-27): zero measured pull for exponent/hex port spellings ⇒ non-proliferation wins today; if a real operator incident surfaces, the narrowing comes back as its own decision card with that evidence. The notice makes any future such incident self-diagnosing either way.

---

Generated by Claude Code

[os-litant]

Triage: label hygiene — this card was already graded in the prior daily-full round (queue/domain:cli/Task; fix the silence, don't touch the accept set) but kept the stale finding label past grading. Removed it (finding ends at first grading per protocol); labels now pm:queue + domain:cli. No change to routing or recommendation.

---

Generated by Claude Code