fix: auto-start WS server in-process and change default port to 20132

[ianriizky]

Summary

• The WS server now auto-starts in-process via instrumentation-node.ts using await import("@/server/ws/liveServer") inside the isBackgroundServicesDisabled() guard. No longer requires a separate sidecar script across all deployment modes (dev, production, Docker, Electron).
• Default WS server port changed from 20129 to 20132 to avoid port conflict with API_PORT (20129) in split-port mode configurations.
• Removed deprecated OMNIROUTE_DISABLE_LIVE_WS environment variable. Consolidated to OMNIROUTE_ENABLE_LIVE_WS (default: enabled) across all code, scripts, and documentation.
• Added LIVE_WS_PORT to docker-compose.yml (env only, no port mapping).
• Live WebSocket path is now derived from the pathname of NEXT_PUBLIC_LIVE_WS_PUBLIC_URL instead of being hardcoded to /live-ws. The path is extracted from the URL (e.g. wss://ws.my-ai.com/my-ws → /my-ws), with /live-ws as fallback. Shared via src/shared/utils/wsPath.ts and used by the handshake response, client hook, and dev proxy.

Related Issues

• Closes #
• Related to #

Validation

• npm run typecheck:core
• npm run test:unit (24 existing tests + 1 new regression test — all passed)
• node --import tsx/esm --test tests/unit/live-ws-public-url.test.ts (7 tests — 5 existing + 2 new path derivation tests — all passed)
• npm run test:coverage
• Coverage is still >= 60% for statements, lines, functions, and branches
• SonarQube PR analysis is green or any remaining issues are explicitly documented below

Tests Added Or Updated

• tests/unit/instrumentation-live-ws.test.ts — new: regression test verifying instrumentation-node.ts imports @/server/ws/liveServer for in-process auto-start.
• tests/unit/chatcore-telemetry-helpers.test.ts — updated: default port assertion 20129 → 20132.
• tests/unit/livews-forward-backoff-4604.test.ts — updated: comment + ECONNREFUSED error message 20129 → 20132.
• tests/unit/live-ws-public-url.test.ts — updated: test URLs 20129 → 20132, and 2 new test cases for path derivation from NEXT_PUBLIC_LIVE_WS_PUBLIC_URL pathname (custom path + default fallback).

Coverage Notes

• src/instrumentation-node.ts change covered by the new regression test (instrumentation-live-ws.test.ts) verifying the liveServer import is present.
• open-sse/handlers/chatCore/telemetryHelpers.ts change covered by existing tests in chatcore-telemetry-helpers.test.ts and livews-forward-backoff-4604.test.ts (both updated to the new port).
• src/app/api/v1/ws/route.ts change covered by live-ws-public-url.test.ts (updated to the new port + 2 new path derivation tests).
• src/shared/utils/wsPath.ts — new shared utility for path derivation. Covered indirectly via the 2 new test cases in live-ws-public-url.test.ts which assert body.live.path.
• src/hooks/useLiveDashboard.ts — client-side path append + runtime handshake path discovery. Not directly tested (client hook), but logic mirrors the server-side helper.
• scripts/dev/standalone-server-ws.mjs — dev proxy path derivation. Not directly tested (dev-only script), but uses the same logic as the shared utility.
• No coverage decrease in any touched file — only string constant changes and one new import.

Reviewer Notes

• Port change: Operators who explicitly set LIVE_WS_PORT=20129 in their .env are unaffected (env var overrides the default). Operators relying on the default need to update firewall/proxy rules from 20129 to 20132.
• Env var removal: OMNIROUTE_DISABLE_LIVE_WS was removed from .env.example, .env, docs/reference/ENVIRONMENT.md, and scripts/start-ws-server.mjs. Operators using OMNIROUTE_DISABLE_LIVE_WS=1 should migrate to OMNIROUTE_ENABLE_LIVE_WS=0.
• Docker: LIVE_WS_PORT added to the x-common anchor and the omniroute-host profile environment. No port mapping added — the WS server binds to loopback inside the container.
• Auto-start guard: The import is wrapped in try/catch (non-fatal) inside the isBackgroundServicesDisabled() block, so a WS server failure won't crash the application startup.
• WS path derivation: The path is parsed from NEXT_PUBLIC_LIVE_WS_PUBLIC_URL at runtime (server-side) and at build time (client-side). Only ws:///wss:// URLs are accepted for path extraction; non-ws URLs fall back to /live-ws. In Docker prebuilt scenarios where the env var is set at runtime but wasn't available at build time, the client discovers the path via the handshake response body.live.path.
• Dev proxy fix: The startsWith("/live-ws") check in standalone-server-ws.mjs was changed to startsWith(LIVE_WS_PATH + "/") to avoid false positives (e.g. /live-ws-custom matching /live-ws).

Code Review

This pull request updates the default live WebSocket port from 20129 to 20132 across the codebase, switches the configuration from a disable flag to an enable flag (OMNIROUTE_ENABLE_LIVE_WS), and introduces a utility to dynamically derive the WebSocket path from the public URL. Feedback on the changes suggests using the standard URL API instead of String.prototype.replace() in src/hooks/useLiveDashboard.ts to safely update the WebSocket URL's pathname and prevent potential string replacement bugs.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

🔀 Cycle moved: base retargeted to release/v3.8.46 — release/v3.8.45 is frozen for the release in progress (#6313). No action needed.

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

@ianriizky thanks for the in-process WS auto-start (+ default port 20132) — merged into release/v3.8.47. 🙏

@ianriizky thanks for the in-process WS auto-start (+ default port 20132) — merged into release/v3.8.47. 🙏

I really appreciate man. I'll look up for another issue you need to solve 🤝.