fix(serve): honor explicit --port over persisted mobile-ws fallback (#8535)

[LesleyMurfin]

Summary

An explicitly pinned orca serve --port <P> now deterministically binds <P>. Previously a persisted mobile-ws fallback port (STA-1511, written to <userData>/mobile-ws-fallback-port.json) was bound before the pinned port (candidatePorts = [fallback, pinned]). Once that file recorded a stale port, every later serve bound the stale port and never attempted <P> — stranding already-paired clients that dial the pinned port, and breaking any health check or SSH tunnel targeting it. There was no CLI way to force the pinned port.

Screenshots

No visual change — headless serve WebSocket transport behavior only.

Testing

• pnpm lint
• pnpm typecheck
• pnpm test — added #8535 regression tests (2 passed, Node 24)
• pnpm build — build:desktop passed (typecheck + relay + cli + electron-vite + web); build:native not run locally (no native code touched by this change)
• Added high-quality regression tests: with a persisted fallback present, an explicit --port binds the pinned port; the default/unpinned case still honors the persisted fallback. Verified load-bearing — reverting only the fallback guard flips the first test to bind the fallback (expected <pinned> to be <fallback>).

AI Review Report

Root cause: the "was the port set explicitly?" signal is erased before the transport sees it. getServeOptions leaves wsPort undefined when --port is absent, but the OrcaRuntimeRpcServer constructor applies wsPort = DEFAULT_WS_PORT (6768) — so by the time ws-transport.start() runs, an explicit --port 6768 is indistinguishable from the default and the persisted fallback pre-empts it.

Fix: thread a wsPortExplicit boolean (serveOptions?.wsPort !== undefined) from index.ts through OrcaRuntimeRpcServerOptions to the runtime. For an explicit pin the runtime does not read/pass the persisted fallback (candidatePorts = [pinned]) and does not persist a fallback on divergence. Default/unpinned behavior and the wsPort === 0 E2E path are unchanged, so STA-1511 paired-device stability is preserved.

Review explicitly checked:

• Cross-platform (macOS / Linux / Windows): pure boolean threading — no OS-specific paths, no path/shell/shortcut/Electron-accelerator surface touched. The Windows/Hyper-V EACCES fallback path and the 0.0.0.0 bind host in ws-transport.ts are untouched; behavior is identical on all three platforms.
• SSH / remote / local: orca serve --port is the remote-host case (operators pin the port for firewall rules and SSH tunnels). The fix makes the pin deterministic across relaunches; local and E2E paths unchanged.
• Agent / integration compatibility: no agent- or provider-specific code involved.
• Performance: no new work in any hot path — one boolean check at bind time.
• UI quality: N/A (no UI change).

Security Audit

• Exposure surface unchanged: the transport still binds 0.0.0.0 exactly as before — not widened. Per-device tokens and E2EE are untouched.
• Path / file handling: an explicit pin now additionally does not write the fallback file, leaving no stale port state on disk; no new file paths are introduced.
• Input handling / command execution / IPC / secrets / dependencies: none affected. No new external inputs, no new dependencies, no new logging of sensitive data.

Notes

• Reproduced on Orca 1.4.137 (Linux, headless); control 1.4.131 not affected. The STA-1511 persistence code has shipped since v1.4.130 (PR fix(mobile): surface disconnected source-control states + keep the mobile WS fallback port stable (STA-1511) #7855); the fallback-first binding order was introduced by PR Harden layout validation, watcher lifecycle, and connection robustness #7924.
• Workaround for anyone hitting this before upgrading: delete <userData>/mobile-ws-fallback-port.json before starting a pinned serve.

Closes #8535

[nwparker]

Thanks for identifying the explicit-pin vs STA-1511 fallback root cause and the integration tests.

Merged #9005 instead (non-draft, verify green): it threads preferPinnedPort so an explicit serve --port binds the pin first when free, while still falling back on EADDRINUSE and preserving default fallback-first for unpaired/auto ports. Skipping the fallback candidate entirely on explicit pins is a stricter tradeoff we preferred not to take.

Closing this draft as a duplicate for #8535.