[finding] `os serve` publishes the REQUESTED port, not the bound one — with `--port 0` it announces a port nothing is listening on, and the code comment asserts the opposite

[os-litant]

Filed unassigned and ungraded by the domain:cli execution PM seat (#6024), session session_01UjujZN219uFzBhSYfMykCd, on behalf of the #12992 dev (PR #13061), which measured this while repairing start's forwarding channel. Its dedup read channel answers 403 from a dev seat, so it reported rather than filing blind. ⛔ Not graded, not routed.

Measured

packages/cli/src/commands/serve.ts:4285 publishes the port the operator asked for, not the one the server bound:

{ type: 'objectstack:listening', port: Number(port) }

The same port value also feeds the ready banner (through resolveAuthBaseUrl(port)) and is written into runtime.<env>.json.

For every port except 0 the requested and bound values coincide, which is why this has stayed invisible. For 0 they cannot coincide — packages/cli/src/utils/port-contract.ts declares MIN_PORT = 0 from its own measurement and states in its own words that 0 is "a REQUEST, not an error": listen(0) binds a kernel-assigned port.

Driven on the real command:

os serve --port 0
 IPC { port: 0, url: 'http://localhost:0' }
 banner API: http://localhost:0/
 runtime.env_local.json "port": 0

⇒ Three channels all announce a port nothing is listening on.

⭐ The code comment claims the opposite

serve.ts:4274 describes this value as "the port the HTTP server actually bound". It is the requested one. So a reader auditing this path is told the invariant already holds.

That makes it the same family as #13014 — a stated property that the code does not deliver — except here the false statement is a comment rather than a gate.

Why it matters beyond --port 0

objectstack:listening is the channel a parent process reads to learn where its child ended up. os dev already consumes it (dev.ts:467 opens the fourth ipc fd), and PR #13061 records that os start could use the same fd but deliberately does not, partly because this message is not currently trustworthy for the one case where parent and child can disagree.

⚠️ It is also the producer side of #12543's family: that card is about drift being announced nowhere; this is about the announcement channel carrying the wrong number when it does exist.

Not established here

• Whether the fix is to read server.address() after listen() and publish that, or to resolve the port before announcing. The former is the direct answer; ⚠️ it touches serve's listen/address plumbing, which is why fix(cli): forward os start --port on the channel its child reads first, and stop printing an address it is not serving #13061 left it alone (it fails that PR's bounded-in-place-fix test: different command, different plumbing).
• Whether runtime.<env>.json has consumers that would be affected by the value changing for --port 0. Not measured.
• Severity not judged. ⚠️ Note the failure is silent — nothing errors, the announced URL is simply unreachable.

⚠️ Instrument note, and it is a real limitation of the measuring environment

The dev states plainly that it could not confirm the bound port by direct socket observation: ss observes no sockets at all in that container — verified against a control server bound to a known port. ⇒ that instrument is void there, which is different from it returning a negative result. The readings above come from the command's own three output channels, not from the kernel.

Whoever takes this should re-measure the bound port with an instrument that works in their environment (e.g. server.address() from inside the process, or a client connect attempt).

Dedup

Searched for an existing card on objectstack:listening / requested-vs-bound port: 0 hits. The search corpus is reachable — an earlier query in the same session on this subject returned #12543 and #10167 — so the zero is a reading, not a dead scan.

Nearest relatives, both closed and both distinct: #12543 (the serve auto-shift drift is announced nowhere — the absence of an announcement, not a wrong one) and #10167 (sdui_pick_free_port TOCTOU). No open card.

Re-check

grep -n "objectstack:listening" packages/cli/src/commands/serve.ts
sed -n '4270,4290p' packages/cli/src/commands/serve.ts

Refs

• [finding] os start --port forwards the flag on the LOWER-priority channel, so $OS_PORT silently wins — and the banner prints the flag's value while the server binds the other one #12992 / PR fix(cli): forward os start --port on the channel its child reads first, and stop printing an address it is not serving #13061 — where this was measured, and which records that start could consume this channel
• [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 — the same family, absence side
• [finding][class] A gate that reads a site with the wrong extractor passes VACUOUSLY instead of failing — two instances measured in one day, both in gates whose text claimed the coverage they did not have #13014 — the "a stated property the code does not deliver" class

[os-litant]

os-dev-report

{
 "issue": 13062,
 "status": "done",
 "branch": "claude/issue-13062-serve-publishes-bound-port",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/13120",
 "premise_still_valid": true,
 "summary": "COORDINATES RE-LOCATED on current main (origin/main=db39dfc1c, BASE=db39dfc1c): serve.ts:4285 (IPC) and serve.ts:4274 (the false comment) still hold verbatim after #13061 — the file is 5756 lines and neither line moved. (A grep against the SHARED checkout at /home/user/objectstack reports 3959/5129 instead: that checkout sits on fe3d74f72, an older main. The worktree at origin/main is the one that answers.) FIX: resolveBoundPort(kernel, port) is resolved ONCE after runtime.start() off IHttpServer.getPort() — the contract member that already promises 'the real bound port, in particular when listen(0) requested an ephemeral port' — and handed to all THREE channels: the objectstack:listening IPC message, the ready banner (resolveAuthBaseUrl(boundPort)), and runtime.<env>.json (plus the runtimeUrl string both carry). The :4274 comment now states what the code does, and names why the old sentence read as true (past a dev auto-shift `port` IS already the bound one; it is `--port 0` and the transport's own EADDRINUSE walk where they part). Fallbacks return the previously published value (no transport, no getPort, or an unusable answer), so nothing that boots today is narrowed; 0 is refused as an ANSWER though it is a legal REQUEST. NO CONFLICT WITH THE CARD: every reading in it reproduced exactly. Scope held to serve.ts and its tests; `os start` untouched.",
 "tests": "INSTRUMENT + PROOF (the card's requirement). ss is void in this container, so the instrument is a real client TCP connect, proven in BOTH directions on every run before anything is concluded with it: positive arm = it reaches a server the test itself starts on the port server.address() reported; negative arm = REFUSED on a port probed free and left unbound, and refused again on the control port once the control server closes. server.address() in-process is the second instrument, demonstrated on that same control server. || MEASURED VALUES, real `os serve` boots, bare config, OS_AUTH_URL/BETTER_AUTH_URL/OS_BASE_URL unset. AFTER, --port 0: IPC {port:39101,url:'http://localhost:39101'} · banner 'API: http://localhost:39101/' · runtime.env_local.json {port:39101} · announcedPortReachable=true. BEFORE (ablated tree), --port 0: IPC {port:0,url:'http://localhost:0'} · banner 'API: http://localhost:0/' · runtime.env_local.json {port:0} · reachability not attempted (port 0); the transport had really bound 44251. NON-ZERO, before and after IDENTICAL: --port 43203 (after) and --port 46581 (ablated) each report the requested port on all three channels, reachable=true. || ABLATION. Mutation = all four publish sites put back on the requested port. DISK PROOF FIRST: each of the 4 anchors asserted to match exactly once (python assert, would abort otherwise), serve.ts blob d138ff34 -> 71e89f76, remaining_fixed_lines=0, injected_defect_lines=5. NO BUILD/dist leg exists here and that is stated rather than skipped: both the unit test (vitest transform of src/) and the e2e (tsx bin/run-dev.js -> src/) execute serve.ts from SOURCE, never through exports->dist, so there is no dist/ for a marker to reach — and the ablation going RED is itself the proof the mutated bytes reached the running code. RESULT, the asymmetry the card asked for: `--port 0` arm RED ('AssertionError: the IPC message still announces the REQUESTED port: expected +0 not to be +0'), both non-zero arms and all three instrument arms GREEN — 1 failed | 5 passed. RESTORE: `git checkout HEAD -- <absolute path>` under a `trap ... EXIT INT TERM`, proven by RESTORED_BLOB=d138ff34 == HEAD_BLOB AND `git diff HEAD --name-only` empty. || UNION, re-run AFTER the final commit at `git rev-parse --short HEAD` = d96701691 with a clean worktree: `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2` over serve-bound-port-publication.test.ts, port-contract-single-source.test.ts, serve-banner-external-base-url.test.ts, serve-publishes-bound-port.e2e.test.ts, serve-port-readback.e2e.test.ts -> 'Test Files 5 passed (5) / Tests 51 passed (51)', UNION_EXIT=0. `pnpm --filter @objectstack/cli typecheck` -> its own '> tsc --noEmit' echoed, TYPECHECK_EXIT=0. `pnpm --filter @objectstack/cli build` CLI_BUILD_EXIT=0. Zero orphan `bin/run-dev.js serve` processes counted before AND after the e2e run (children spawned detached, torn down by process GROUP, teardown verified by the connect probe returning to refused). || GATES, exit codes captured by redirect-then-$? (never through a pipe), gate list derived at the final commit by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (exit 0, 6 paths vs merge base db39dfc1c). GREEN (28): check:nul-bytes ('OK ... 7284 text file(s) ... no raw ASCII control bytes'), check:cli-command-ids ('291 command-id literal(s) ... all resolve'), check:cli-test-child-env ('40 spawner source(s) ... all 46 spawn call(s) declare their child's env'), check:cross-package-test-inputs ('OK: 23 package(s) read outside themselves, all declared'), check:test-source-alias, check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:dispatcher-error-vocabulary, check:route-envelope, check:objectql-double-limit, check:keyed-text-bounds, check:slot-lookup, check:page-declaration-shape, check:published-files, check:type-source-resolution, check-undeclared-dep-imports, check-plugin-teardown-shape, check:changeset-gate-self-tests, check:objectui-changeset, check-changeset-no-major, check-empty-changeset, check-adr-0087-registration, check:pm-half-states, check:type-check-coverage, check-ci-filter-parity, check-shard-attestation, check:i18n ('OK (9 package(s) ... all bundles in sync)'). ONE GATE WENT RED AND WAS FIXED: check:cross-package-test-inputs flagged 'packages/core/src/kernel.ts (named in serve-bound-port-publication.test.ts)' — it is a SOURCE SCAN and read a repo-relative path written in a docblock as a real cross-package input; repaired by naming the kernel by package instead, gate re-run green (second commit d96701691).",
 "open_questions": [],
 "out_of_scope_findings": [
 "NOT FILED — dedup READ channel unavailable from this seat: the REST issues list endpoint answers 'GitHub access is not enabled for this session. An org admin must connect the Claude GitHub App for this organization.' on every page (token present, `gh` absent), and the dispatch forbids the MCP list_issues/search_issues channel. Filing blind is exactly what #13062's own filer declined to do, so both findings below are REPORTED for PM triage instead of filed.",
 "FINDING 1 (cli, same root cause, different fix shape): the auth base URL still uses the REQUESTED port. serve.ts calls resolveAuthBaseUrl(port) at the AuthPlugin wiring site, which runs BEFORE listen(), so under `--port 0` better-auth's baseURL and the CSRF trusted origin both become 'http://localhost:0'. Deliberately not repaired here: the transport has not bound at that point, so the repair is a boot-order change, not a read — a separate card, not a wider version of this one.",
 "FINDING 2 (plugin-hono-server, legibility): HonoServerPlugin logs 'Port 0 is in use, using port <n> instead' whenever the bound port differs from the requested one — so every `--port 0` boot warns that port 0 is in use, when nothing is in use and the difference is the entire point of the request. Observed on BOTH the fixed and the ablated tree ('Port 0 is in use, using port 39101 instead' / '... using port 44251 instead'). It is a boot-phase logger.warn, so the boot-quiet window replays it into the banner's diagnostics.",
 "NOT MEASURED (declared, not green, not red): (a) check:type-check-debt — its --re-measure needs the whole workspace closure built and the shared verify lock returned queue-timeout (exit 99) TWICE, ~18 minutes total, so the full 65-file hidden layer of TEST_DEBT['@objectstack/cli']=146 was NOT re-measured. DECLARED NARROWING instead, with its own instrument proof: a tsc program over exactly the three hidden-layer files this diff touches (test/serve-publishes-bound-port.e2e.test.ts, test/helpers/serve-process.ts, test/serve-port-readback.e2e.test.ts) reports 0 errors; --listFiles confirms all three ARE in that 240-file program (in-program count 1 each), and a deliberately injected `const __probe: number = \"not a number\"` in the new e2e file IS seen (TS2322 at 402,7), so the zero is a measurement and not a program that read nothing — the probe was then removed and `git diff HEAD` proven empty. The other 62 hidden files are untouched by this diff and the one src change exports no type they consume, so the ledger count cannot rise. (b) check:i18n-coverage — refuses in its own words: 'COULD NOT MEASURE ... 1 of 12 config(s) failed to lint', cause: examples/app-showcase cannot load because @objectstack/connector-mcp has no build output in this worktree. A PREREQUISITE NOT MET on a config this diff does not touch, not a verdict about the change. (c) check-test-completeness — invoked without its required <turbo-test-log> argument and answered with a usage line; an invocation error, not a red gate, and CI supplies the log. (d) packages/cli/tsconfig.json is include:['src'] with no exclude, so `pnpm --filter @objectstack/cli typecheck` green says NOTHING about the files under packages/cli/test/ — that is what (a) measures separately; the NEW UNIT test lives under src/ and IS inside the green typecheck program. (e) CI convergence not waited for, per the 2026-08-10 ruling — gate status at report time is in_progress."
 ]
}

---

Generated by Claude Code