[roodboi]

Root cause

private_control_stops_only_matching_publisher_and_preserves_replaced_path (and three other tests in packages/runtime-core/tests/stream_relay_contract.rs) picked a port with free_loopback_port(). That helper bound 127.0.0.1:0, read the port, and dropped the listener before the publisher bound it. Another test running in parallel could take the port in that window. The publisher's bind() then failed, it exited 73 (EX_CANTCREAT, the stream relay's "frontend could not be bound" code in guest/stream-relay.c) without a readiness line, and the helper reported stage: "readiness EOF". That matches CI run 39284084093, job 118164984179.

I reproduced it locally on unmodified next (ec223cd): 3 of 300 parallel runs of the contract binary failed in this test with PublisherStartupFailure { stage: "readiness EOF", status: unix_wait_status(18688) }, which is exit 73.

Fix

The publisher now binds the port itself, so no released port is ever handed to it.

• stream-relay --publish 0 (exactly "0") binds a loopback port that the kernel chooses. It reports that port as ready <port>\n, read back with getsockname after the listener and the optional control socket are bound.
• The change is backwards compatible:
  • Explicit ports (1-65535) and --publish-unix still write the bare ready\n line.
  • 00, --publish-unix 0 and relay-mode port 0 are still refused with 64.
  • The only production caller (provider/publisher.rs) passes an explicit port and is unchanged.
• The contract is documented in the comment block above main in guest/stream-relay.c.
• Test changes:
  • Every test that used the released probe now publishes on port 0 (ephemeral_publisher) or holds the port it needs for the whole test.
  • free_loopback_port() is removed.
  • The exit-73 retry loop in control_startup_refuses_occupied_and_nonprivate_paths_without_retaining_publisher_resources is removed: its TCP leg now always reaches the control path.
• try_frontend_publisher reads one bounded readiness line of at most 12 bytes. It accepts ready\n, or ready <canonical nonzero port>\n for port 0.

Tests

The new test is ephemeral_publication_reports_its_bound_port_and_explicit_ports_keep_bare_ready. It checks that:

• the exact-0 form is the only one admitted. Refusals are bounded by a 3 s deadline, so a wrongly admitted publisher fails the test instead of hanging it.
• two port-0 publishers report distinct ports, and each port is the publisher's live listener (AddrInUse on bind, connect succeeds).
• explicit ports keep the bare ready\n line. This leg still needs a released probe to choose a concrete port, so it retries at most 3 times, and only on the publisher's confirmed bind refusal (readiness EOF with exit 73).

Mutations, each run against the contract suite:

Mutation in stream-relay.c	Result
Port 0 prints the bare ready line	killed: 4 tests fail with readiness marker
Reported port is the bound port + 1	killed: 3 tests fail (AddrInUse/connect asserts)
Any all-zero string (00) selects an ephemeral port	killed: command was admitted instead of refused
Explicit TCP ports print ready 1	killed: explicit-port leg fails with readiness marker

Evidence

All on an M-series macOS host under heavy shared load (load average 26-90).

• Repeated parallel runs of the stream_relay_contract test binary (--test-threads 16, several processes at once):

  Build	Runs	Port-race failures (exit 73 / readiness EOF)
  base next	100 (4 at a time) + 200 (8 at a time)	3
  this branch	100 (4 at a time) + 400 (8 at a time)	0

  Every other failure on both builds is the unrelated EINVAL in Relay::connect described under remaining gaps.

• cargo +1.97.1 fmt --check: clean.

• clippy --all-targets --all-features -D warnings (Zig 0.15.2): clean.

• bun run check:local: clean.

• bun run test:local: pass.

• All-features cargo test (CI's command): 1270 passed, 2 failed. The 2 failures were graph_timeout in provider::graph::native::runtime::tests::two_*, which do not use the relay. All 3 two_* tests pass when rerun serially.

• bun run --cwd packages/cli typecheck: 0 errors. check: 0 errors (existing warnings only).

• Full bun run test with Bun 1.4.2 (mise x bun@1.4.2): did not pass on this host. The parallel run hit load average 30-90 and had 1270 timeout and fixture-cascade failures across 118 files. Rerunning each of those files serially with --timeout 60000 passed 98 of them. 20 files still fail: the native-compose-* family plus native-authored-project-start, -recovery and -process-incarnation. Their errors are Completed-job worktree acceptance refused, storage.enroll stalls of 31 s or more, and fixture-settlement cascades. The TypeScript suite does not read or run either changed file; the only TS mention is the native-stream-relay feature-name string in native-candidate-authored-artifact.test.ts. Two of these files (native-compose-runtime-metadata-command, native-compose-storage-fence-cost) fail the same way with the base next relay sources restored (1 pass, 6 fail). I am treating these as host and worktree failures, not regressions. Hosted CI is the authority here, and next has since landed fix(native): keep storage carrier commands alive through host stalls #356 ("keep storage carrier commands alive through host stalls").

• gitleaks 8.30.1 over origin/next..HEAD: no leaks.

Remaining gaps

• Hosted CI on macOS (Candidate core) has not run on this head yet.
• Another flake in the same file, outside HACK-1284 and not fixed here: Relay::connect calls set_read_timeout(...).unwrap() after connecting. On macOS, setsockopt returns EINVAL once the relay has already closed the accepted socket, as it does for the excess connection or an unavailable target. This failed connection_limit_refuses_excess_without_disrupting_existing_streams and occupied_socket_is_not_unlinked_and_unavailable_target_fails_connection in about 1% of parallel runs, on both base and this branch.
• provider/publisher.rs's macOS test fixture uses the same released-probe pattern. That file is outside this unit and is reported separately.
• The releases_port check (connect fails after stop) could still in theory see another process's listener on a reused ephemeral port. This was not observed.

Refs HACK-1284

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[linear-code]

HACK-1284

[blacksmith-sh]

Found 1 test failure on Blacksmith runners:

Failure

Test	View Logs
native-config-down-hooks (17.3s) — Each finite down mode starts a ready owned generatio n/ native-config-down-hooks (17.3s) — Each finite down mode starts a ready owned generatio n	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}