Harden holdSpecificPort: report bound port, guard close, fix doc

- Report the actually-bound port from server.address() rather than echoing
  the input, so a stray holdSpecificPort(0) reports the OS-assigned
  ephemeral port instead of a misleading 0.
- Guard the bind-error handler's server.close() against the never-listened
  case so a synchronous throw there can't leave the outer promise unsettled.
- Correct the startIsolatedRealmStack publicPortReservation doc: it's also
  omitted for a caller-supplied realmServerURL or an explicit
  compatRealmServerPort, not only a reused context.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: habdelra

packages/realm-test-harness/src/isolated-realm-stack.ts

@@ -623,9 +623,10 @@ export async function startIsolatedRealmStack({
    *  upstream by `resolveFactoryRealmServerURL` and threaded down through
    *  the template build. We adopt it (so the sibling worker-manager /
    *  realm-server allocations below can't steal the number) and release it
-   *  immediately before the compat proxy binds. When omitted, the public
-   *  port came from a reused context, so we hold the specific number
-   *  ourselves. */
+   *  immediately before the compat proxy binds. Omitted whenever the public
+   *  port wasn't freshly allocated with a holder — a reused context, a
+   *  caller-supplied `realmServerURL`, or an explicit `compatRealmServerPort`
+   *  — in which case we hold the specific number ourselves. */
   publicPortReservation?: PortReservation;
 }): Promise<RunningFactoryStack> {
   if (realms.length === 0) {

packages/realm-test-harness/src/shared.ts

@@ -499,7 +499,14 @@ export async function holdSpecificPort(port: number): Promise<PortReservation> {
   return await new Promise<PortReservation>((resolveOuter, rejectOuter) => {
     let server = createNetServer((socket) => socket.destroy());
     let onError = (error: NodeJS.ErrnoException) => {
-      server.close();
+      // The bind failed, so the server never listened — close() hits the
+      // not-running case. Guard it so a synchronous throw here can't strand
+      // the outer promise without settling it.
+      try {
+        server.close();
+      } catch {
+        // never listened — nothing to close
+      }
       if (error.code === 'EADDRINUSE') {
         diagnosePortConflict(port)
           .catch(() => '')
@@ -519,9 +526,16 @@ export async function holdSpecificPort(port: number): Promise<PortReservation> {
       // Swallow late errors after a successful bind so they don't surface
       // as unhandled 'error' events.
       server.on('error', () => {});
+      // Report the actually-bound port. For a concrete non-zero port that's
+      // the requested number; if a caller ever passes 0, listen() picks an
+      // ephemeral port and this reports the real one instead of a misleading
+      // 0.
+      let address = server.address();
+      let boundPort =
+        address && typeof address !== 'string' ? address.port : port;
       let released = false;
       resolveOuter({
-        port,
+        port: boundPort,
         release: () =>
           new Promise<void>((resolveClose, rejectClose) => {
             if (released) {