test(create-objectstack): boot the scaffold-e2e probe blocks on a HELD port, and show what a block said when it fails

[objectstack-fleet]

Fixes #20516
Clause-②: no

What this changes

One file, packages/create-objectstack/src/scaffold-e2e-boot-probe.test.ts, and it is a tests-only diff (see Publish surface).

1. Every verdict on a block's run now carries the block's own output. Each assertion on a block's exit status or duration passes said(r) as its failure message. That message holds the block's ::error:: line, the server log it dumps, its exit code and its duration. The merge-queue failure printed only a bare expected 1 to be +0; that message now names its exit path.
2. The port is HELD from the kernel's answer until our server binds it. pickFreePort is gone. It was an advisory "free right now" probe that let go of the port, which sat inside ip_local_port_range. portHolder() spawns a child that asks the kernel for a port (listen(0)) with SO_REUSEPORT and keeps it bound. The os start stub and the container stub bind the same port with the same flag, so they join the holder's binding instead of racing for the number. Each ends the holder once its own listener is up. The port is bound at every instant between the two. No outbound connect() and no other listen(0) can be given it, and any binder without SO_REUSEPORT is refused with EADDRINUSE.
   • The holder accepts and resets every connection. The block's pre-flight curl -fsS therefore still reads "nothing is serving". A holder that accepted without answering would hang that curl, which has no --max-time.
   • Before it announces its port, the holder binds a second reusePort socket to the port and lets go. A platform that ignored the flag fails there, with a message naming reusePort. Without that check it would fail later in the block as Port N is already in use, which is also the one line a lost port race prints. A new control pins this diagnosis.
3. Pins (triage grade 5879541220). Both os start blocks (scaffold-local and registry-canary) share one it body per case. The "accepts the server it booted itself" case now does four things:
   • asserts the holder serves nothing;
   • aims a deliberate occupier at the handed-over port and asserts it is refused with EADDRINUSE;
   • runs the block and asserts it passed;
   • asserts the block ran on that port: the stub's answer names the port it bound ("port":N).

The Docker leg's two callers of the same helper (base port 38900) are converted in the same edit. They have the same defect class, the same file, the same mechanical shape and the same gate family. Removing the advisory helper left them no other port source.

Dispatch hypotheses, measured

• H0: no existing helper hands a held port to a child.

  • packages/cli/test/helpers/serve-process.ts: reservePort() binds port 0 and then closes it (its own docblock calls it "still TOCTOU"). holdPort() holds a port but never hands it over.
  • flaky: sdui_pick_free_port is a TOCTOU probe — it closes the probe socket before returning, so two concurrent callers scanning from 5180 are both handed 5180 (dequeued PR #10157 from the merge queue) #10167 and smoke_pick_free_port in scripts/publish-smoke.sh is the same TOCTOU probe as #10167 — concurrent callers scanning from 3210 are all handed 3210 #10212 landed a host-shared claim registry for shell scripts, built on flock.
  • [finding] serve-publishes-bound-port e2e races its own port pick on a shared CI runner — dropped PR #15073 from the merge queue (expected 40733, got 40734) #15273 landed a change to the asserted quantity.
  • So portHolder() is new. It reuses this file's own neighbour() instrument (announce protocol and diagnoses) through two new options instead of adding a second spawner.

• H1: confirmed. The merge-queue failure's exact shape was reproduced on this host. A listener that serves nothing held the stub's port, and the block exited 1 on its liveness check after 2.0s. With the old assertion form the output was AssertionError: expected 1 to be +0 and nothing else. With the new form, the same kind of run printed:

  AssertionError: the block exited 1 after 2.025s — its own output:
  --- block output ---
  ::error::the server this step started exited before becoming healthy
    Port 52750 is already in use.
       ObjectStack does not auto-select a different port in production mode: expected 1 to be +0
  

• H2: false as literally stated, so the pin is aimed where it can fail. Measured on this host: with an occupier bound on 38700 for the whole run, the OLD advisory source handed out 38701 and the old test passed. A bind probe skips a port that is held the whole time. The old helper could only lose to something that arrived between its probe and the stub's bind. The occupier pin is therefore aimed at the port the source handed over, after the source answers.

  • Ablation against the old advisory source, measured on this host: red, with this control is vacuous: the occupier was supposed to fail and it came up on port 38702.
  • The same pin against the holder only runs on Linux (see Verification).

• H3: confirmed. Both os start blocks share one set of it bodies (the OS_START_STEPS loop), so both run on the held port.

Verification

This dispatch ran on macOS (darwin). The suite is gated on process.platform === 'linux' (RUNNABLE), and on macOS libuv answers ENOTSUP to reusePort.

• NOT MEASURED locally:

  • the suite's green path on the new port source;
  • the holder-side half of the occupier ablation.

  Reason: this dispatch has no Linux host. CI's Test Core (ubuntu-latest) runs the file on this PR. On this host the file reports 14 skipped cases; the base has 13 by count, and the extra one is the new control.

• Measured on this host, from an uncommitted scratch copy with the platform gate lifted. The copy was deleted afterwards and the tree checked clean.

  • H1, in both assertion forms.
  • H2 as literally stated.
  • The occupier ablation against the old advisory source.
  • portHolder() refusing loudly where reusePort is unsupported: the port holder never came up on a kernel-assigned port ...: its listener refused to bind: ENOTSUP.
  • Every child program text was also syntax-checked the way the child runs it.

At HEAD 0d76b886f4, after merging origin/main at 397572ed5d:

• pnpm --filter create-objectstack typecheck: exit 0. tsc --listFiles includes the test file.
• pnpm --filter create-objectstack exec vitest run --maxWorkers=2: 15 files passed, 1 skipped; 219 tests passed, 14 skipped.
• pnpm lint: exit 0 in 29s. The changed file is linted, not ignored (eslint JSON: 1 file, 0 errors, 0 warnings).
• node scripts/check-issue-citations.mjs --base origin/main: exit 0, no issue citations added.
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 52 families. Reconciled with --ran, exit codes recorded:
  • 49 ran, all exit 0.
  • 3 are NOT MEASURED: pnpm check:dual-build-cjs-loads, pnpm check:lean-entry-closure and pnpm check:type-check-debt. Each exited 3 with PREREQUISITE NOT MET, because each reads every workspace package's built dist/ and this worktree built only this package's closure. None of them can move on a diff to one test file that appears in no build output and in no other package's type program.

Declared narrowing — verification ran UNLOCKED. scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the command below was run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for this
run, nor for any sibling agent in this container while it ran.

pnpm --workspace-concurrency=2 --filter 'create-objectstack^...' build
pnpm --filter create-objectstack typecheck
pnpm --filter create-objectstack exec vitest run --maxWorkers=2
pnpm --filter create-objectstack exec vitest run --maxWorkers=2 -t SCRATCH src/zz-scratch-issue-20516.test.ts
pnpm --filter create-objectstack build
pnpm --filter create-objectstack typecheck && pnpm --filter create-objectstack exec vitest run --maxWorkers=2

Publish surface

Tests-only, so there is no changeset. I built create-objectstack and grepped its files (dist, README.md, CHANGELOG.md):

• PORT_HOLDER_STUB, portHolder, STUB_PORT_HOLDER_PID and reusePort: 0 hits each.
• Positive control, summarizeTree (an export of src/created-summary.ts): found in dist/.

The skip-changeset label is the seat's to apply.

Acceptance notes

• The hand-over technique does not carry over to packages/cli/test/helpers/serve-process.ts. There the process that binds is the real os serve, which binds without SO_REUSEPORT. A holder could only let go before that bind, which is the reserve-then-release race that helper's docblock already declares. Noted, no card (carrier: none).
• With SO_REUSEPORT, any same-user socket that also sets the flag can join the held port. Nothing else in this repository sets reusePort: git grep finds no hits outside this file. The kernel also never gives another listen(0) a port that has a live listener, so concurrent runs of this file get distinct ports.
• Only the status and duration assertions carry the block-output message. The toContain assertions already print the received output when they fail.

---

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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

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 397572ed5da04c14eed7b4bf934a4c353822df6c → packageMentionDocs.

[objectstack-fleet]

skip-changeset: applied by the domain:cli seat on its own reading (tests only)

_{domain:cli execution PM seat #6024 · session local_1d2a197c-c20e-4e90-9be8-413d4d432289 · written 2026-09-28T23:23Z}

• The diff: one file, packages/create-objectstack/src/scaffold-e2e-boot-probe.test.ts (+220 −69), at head 0d76b886. No .changeset/*.md is added or edited.
• What ships: create-objectstack's package.json files is dist, README.md and CHANGELOG.md. A src/*.test.ts file is not in the tarball, and the dev measured the new helpers (portHolder, PORT_HOLDER_STUB) with 0 hits in the shipped files, using a positive control that is found in dist/.
• So: tests only, with no consumer-visible change. The repo's tests-only route is this label; ⛔ not an empty changeset. Check Changeset re-runs on the label.