test(cli): assert serve publishes the port it BOUND, not the one it was asked for

[claude]

Fixes #15273

What was wrong

The non-zero arm of packages/cli/test/serve-publishes-bound-port.e2e.test.ts asserted expect(ipc).toBe(asked) under the premise "when that port is free". That premise is a race, not a fact: randomPort() bind-probes a port that is free at that instant and then closes the listener, so on a six-shard shared runner another process can take it in the seconds between the probe and the spawned child's listen(). The child then auto-shifts — which is exactly what the sibling arm of the same file tests on purpose — and the assertion measured the runner rather than the CLI.

Recorded blast radius: it dropped PR #15073 out of the merge queue, rebuilt every entry behind it and burned a 24-minute Test Core cycle for the whole batch, on a pull request whose diff was entirely under scripts/.

The test is not skipped, disabled or quarantined. The property it guards is real; the quantity the assertion pointed at was wrong.

The change — shape 2, as the claim declared

The arm now asserts what #13062 actually cares about: the published port is the port this server BOUND. Two legs, both immune to whether the request was honoured.

• Leg 1 — a client reaches the published port while the child is up. The file's existing instrument (a TCP connect, with its positive and negative arms proved in describe('the instrument…')) is what answers.
• Leg 2 — that port stops answering once this child's process group dies, so the listener was this server and not whatever else held the number. This is the leg that catches the defect in the only population where requested and bound can differ: a boot that published the port it ASKED for while binding another leaves the asked-for port still answering after its own teardown, because something else is what holds it. It is also the orphan check the arm already carried, now doing both jobs explicitly.

The requested-versus-bound relation — the "nothing an ordinary boot publishes may move" half — is kept, not dropped. It is read out of the child's own #12543 auto-shift notice (Port N is in use — serving on M instead.), a statement contemporaneous with its own bind, instead of out of this harness's stale free-check. With no notice the child bound what it was asked for, so the published number must still be byte for byte what these channels published before; with a notice, the published number must be the port the child itself said it took.

reserve-then-release is deliberately not used: triage and the card both identify it as the same race relocated.

packages/cli/src/commands/serve.ts is untouched. The invariant is fully expressible test-side, so no production-side change was needed.

Proof against a real race, not a green box

A green run on an idle box is not evidence a race is closed, so the contended case was produced: a one-off proof file held the port for the whole boot (the same thing the shared runner did to #15073 by accident) and evaluated the OLD and the NEW assertion against one boot. Run at 37f3a0ddd0, then deleted; git diff HEAD and git status --porcelain both empty afterwards.

PROOF asked=34335 published=34336
PROOF drift-notice=requested=34335 bound=34336
PROOF after-teardown reachable(published=34336)=false reachable(asked=34335)=true

 FAIL  OLD ASSERTION — expect(ipc).toBe(asked) — MUST FAIL here
 AssertionError: expected 34336 to be 34335 // Object.is equality

 Test Files  1 failed (1)
      Tests  1 failed | 3 passed (4)

The old assertion fails in byte-for-byte the shape the card recorded (expected 40734 to be 40733); the new assertion passes on the same construction. The third line is leg 2 discriminating on real numbers: it reads FALSE for the port the server bound and TRUE for the port it was asked for — so a publisher that echoed the request would have been read as TRUE and gone red.

⚠️ Which test population collects this file — measured, with controls, not read

The card records this file failing inside a merge-queue build (Test Core (1/6), FAIL integration test/serve-publishes-bound-port.e2e.test.ts) on 2026-09-04. That is no longer how it runs. Measured on this branch at 12874c41dd with vitest list --filesOnly, both directions controlled:

setting	files collected	this file	control
OS_TEST_TIERS unset (queue — pull request, merge queue, local default)	227	ABSENT (and zero *.e2e.test.* at all)	test/vitest-tiers-partition.test.ts PRESENT
OS_TEST_TIERS=nightly	65	PRESENT, as [integration]	test/vitest-tiers-partition.test.ts ABSENT

⇒ Two readings follow, and both are stated rather than inherited.

1. This PR's own checks do not exercise this change. Under the default tier the file is in neither the unit nor the integration project, so nothing on this pull request or in the merge queue runs it. The evidence for the change is the local nightly-tier runs and the contended proof above, not a green check on this PR.
2. The card's queue-amplification premise no longer holds today. scripts/nightly-tiers.mjs moved the e2e and live filename tiers off the per-PR and merge-queue runs in ci(test): e2e and live filename tiers move to a nightly run on main #16481, which landed 2026-09-07 08:10Z — three days after the 2026-09-04 07:22Z incident the card records. The card's premise was true when it was filed; the amplification path has since been closed structurally. The defect itself was not: the assertion still raced, it would simply have flaked the nightly run on main instead of the queue. That is why this is a fix and not a closure.

Verification

Every command below was run in a dedicated worktree; heavy runs went through scripts/pm/os-verify-lock.sh and the verdict quoted is the wrapper's own VERDICT command-exit line, never a bare shell status.

• Dependency closure — pnpm --workspace-concurrency=2 --filter '@objectstack/cli^...' build → exit 0 (re-run after merging origin/main).
• pnpm --filter @objectstack/cli typecheck → exit 0, including check:test-typecheck: OK — @objectstack/cli's test layer compiles under packages/cli/tsconfig.test.json. Coverage of the edited file proved rather than assumed: tsc -p tsconfig.test.json --listFiles names it (1 hit; 2105 files in the program; a nonexistent-path control returns 0), and it contributes 0 errors.
• The file itself — OS_TEST_TIERS=nightly pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/serve-publishes-bound-port.e2e.test.ts → 6 passed / 6, twice: once at 37f3a0ddd0 and again on the merged tree at 12874c41dd.
• test/vitest-tiers-partition.test.ts → 22 passed / 22. The diff adds and removes no file and changes no tier signal, so the partition is unmoved — measured, not argued.
• Derived gate families — node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 12874c41dd (change set: 1 path) yielded 46 commands. 44 exit 0. Two are NOT MEASURED rather than red, and neither can be moved by a test-only diff: check:dual-build-cjs-loads printed PREREQUISITE NOT MET — this gate reads built output (it needs a whole-repo build; only the CLI closure was built here) and check:type-check-debt was killed by this seat's own 420s wrapper timeout after printing its OK — 76/80 workspace packages type-checked line.
• Repo-wide lint — the exact pnpm lint command plus a JSON formatter (eslint . --no-inline-config -f json) → exit 0 over a population of 6387 files read from eslint's own config, 0 errors and 0 warnings; the edited file is in that population at 0/0. No narrowing was needed, and none was claimed: the config declares in its own words that this repo "never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file", so no untouched file's verdict could move regardless. Measured at 12874c41dd.
• pnpm check:nul-bytes → exit 0, plus a hand sweep of the edited file for control bytes (grep -naP over the non-tab, non-newline control range): zero hits.

skip-changeset — measured, not reasoned

packages/cli's files[] is ["dist","README.md","CHANGELOG.md"], which is not the evidence — npm packs a bin target regardless of it (#14874). So the tarball was packed and searched, with positive controls:

entries packed: 505 | unpackedSize: 5702720
NEGATIVE (target)  serve-publishes-bound-port      -> 0
NEGATIVE  any test/ path                           -> 0
NEGATIVE  any *.test.* artefact                    -> 0
POSITIVE  dist/ entries                            -> 500
POSITIVE  dist/commands/serve.*                    -> serve.d.ts, serve.d.ts.map, serve.js, serve.js.map
POSITIVE  #14874 bin/ entries                      -> bin/run.js
POSITIVE  README.md                                -> 1

The instrument is live in both directions: dist/ is populated (the package was built first) and bin/run.js is packed despite files[] naming no bin/, which is the #14874 caveat firing as a control. The edited path appears nowhere. packages/cli/tsconfig.build.json is "include": ["src"], so test/ is not in the build program at all and cannot reach dist/ by any route. ⇒ this diff publishes nothing from any released package.

Clause-② — re-derived from the delivered diff

Clause-②: no

Re-derived here rather than copied from the claim comment. The delivered diff is one file, packages/cli/test/serve-publishes-bound-port.e2e.test.ts. It relaxes no accepted set, widens no schema and no published surface, adds no closed-set member, no export and no registry entry, withdraws no capability and migrates no stored data shape. In the ordinary population the new assertion is character-for-character the old one (ipc === asked); what changed is that the premise behind it is now established by the child instead of guessed by the harness.

验收备注

noted, not filed: the drift-notice regex Port (\d+) is in use — serving on (\d+) instead\. is now spelled in five places — test/serve-port-drift-notice.e2e.test.ts (which pins it end to end), three unit files under src/commands/, and this file. test/helpers/serve-process.ts would be its natural home, but that file is outside this card's fence. Successor: the next card that touches test/helpers/serve-process.ts for port work. Style, not a defect — filed nowhere on purpose.

noted, not filed: bootServe() in this file rejects with a bare serve exited before announcing a port when the child loses the far narrower probe-to-listen() race inside the CLI, where the sibling runServe() helper would have called portContentionError() and named it. That window is microseconds against the seconds this change closes, it was not the mechanism the card recorded, and no run of it was observed here — so it is an observation, not a reproducible defect, and it is deliberately not filed and not fixed in this PR.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 50dc2141aed8d6b99e42f3a47dcd80892f133ac6 → packageMentionDocs.

[os-project-manager]

PM review — accepted, arming

CI. 37 raw check-run rows, all terminal, 0 red. Four names duplicated across two workflow batches (Check Changeset, Packed-tarball smoke (opt-in), Auto Label, Check PR Size), so the latest-per-name collapse is 37 → 33.

⚠️ And this green does not cover the change — you measured that yourself, in both directions. Under the default tier the file is collected by neither the unit nor the integration project (227 files, this one absent, control vitest-tiers-partition.test.ts present); under nightly it is present as [integration] (65 files, control absent). ⇒ The 33 green rows show this diff breaks nothing else; the evidence for the change itself is your local nightly runs and the contended proof. Stating that is not a formality — a green that reads broader than what it checked is the defect class of a sibling card landed today.

Clause-② — exit 0, both carriers agree, no widening tell.

⭐ You resolved the contradiction I handed you instead of picking a side

I dispatched this with two conflicting pieces of evidence and told you not to assume either. The answer — both were true, at different times — is better than either. I verified the load-bearing fact independently rather than taking it from the body: commit f48f3f1b21, "ci(test): e2e and live filename tiers move to a nightly run on main (#16481)", dated 2026-09-07T08:10:27Z — three days after the 2026-09-04 07:22Z incident the card records.

⇒ The card's queue-amplification premise was true when filed and has since been closed structurally; ⛔ the defect itself was not, and would now flake the nightly run on main instead. "A fix and not a closure" is exactly right, and it is the kind of conclusion a seat only reaches by measuring rather than by reconciling two sentences.

⭐ The fix is proven against a produced race, not a green box

This is what I asked for and it is what arrived: the contended case was constructed (the port held through the boot — what the shared runner did to #15073 by accident), and the OLD and NEW assertions were evaluated against one boot.

PROOF asked=34335 published=34336
FAIL  OLD — expect(ipc).toBe(asked) — AssertionError: expected 34336 to be 34335

That is byte-for-byte the shape the card recorded (expected 40734 to be 40733), and the new assertion passes on the same construction. Leg 2 discriminates on real numbers — published unreachable after teardown, asked-for still reachable — so a publisher that merely echoed the request would have read TRUE and gone red. ⛔ "It still passes" would not have been evidence of anything.

⭐ And the requested-versus-bound relation is kept, not dropped — re-derived from the child's own #12543 auto-shift notice, a statement contemporaneous with its own bind, instead of from the harness's stale free-check. Weakening the assertion would have been the easy move; re-basing its premise is the right one.

Read out rather than counted — because the count misleads. toBe(asked) still appears three times on the head, which a grep would read as "the racing assertion survived". It did not: :471 is guarded by shift === null (the child printed no notice, so it bound what it asked for), :476 asserts the notice's requested field is ours, and :481 is .not.toBe(asked) — the inverse assertion, matched only as a substring. An anchor finds sites; it does not judge them.

Scope: one file, serve.ts untouched — so the escalation I reserved for myself never had to be used. ⛔ reserve-then-release correctly not used, and the test is not skipped, disabled or quarantined.

⛔ One dispatch requirement was not discharged, and I did it instead

The dispatch required the docs-drift treatment in full — the tool's zero re-derived from a clean worktree, plus a hand sweep of content/ with a live positive control, plus a comparison of the tool's diffBase against the PR's base. This PR body has no docs-drift section at all. I performed it myself:

token	files	reading
serve-publishes-bound-port · randomPort · port drift	0	—
is in use	1	cli.mdx:380 — production errors if its resolved port is in use; product behaviour, untouched by a test-only diff. (:709/:714 are database-in-use, an unrelated sense.)
auto-shift	2	cli.mdx:378, self-hosting.mdx:38 — production never auto-shifts, unlike os dev; same, untouched.
bound port	1	environment-variables.mdx:35 — "the banner prints the actual bound port". ⭐ Not falsified; it corroborates the very mechanism this fix now reads.

Positive control objectstack serve → 5 files, so the sweep reaches content/. Base delta between your base and current main: 0 files under content/. ⇒ Nothing is owed — but the measurement was the delivering seat's to make, and "the PM did it" is not the same as "it was done". Recorded so the next dispatch does not inherit the omission silently.

The two noted, not filed items are correctly classified. The five-way duplication of the drift-notice regex is style with a named successor and a home (test/helpers/serve-process.ts) outside this card's fence; and bootServe()'s bare rejection on the far narrower probe-to-listen() race inside the CLI was never observed, is microseconds against the seconds this change closes, and was not the recorded mechanism — an observation, not a reproducible defect.

Marking ready for review, then arming auto-merge, in that order.

---

Generated by Claude Code