Function getFreeHashPort

src/tools/launch-tool/utils/dev-server-manager.ts:95–124

(workspacePath: string, _startPort: number = DEFAULT_PORT)

 * @throws Error if no ports available in ±10 range around hash-based port
 */
export async function getFreeHashPort(workspacePath: string, _startPort: number = DEFAULT_PORT): Promise<number> {
    // Calculate this workspace's hash-based port
    const preferredPort = calculateHashPort(workspacePath);

    // Try preferred port first
    if (await isPortAvailable(preferredPort)) {
        logger.printInfoLog(`Using workspace-preferred port: ${preferredPort}`);
        return preferredPort;
    }

    // If preferred port is taken, try nearby ports (±10 range)
    // This handles edge case where same workspace runs twice simultaneously
    logger.printInfoLog(`Preferred port ${preferredPort} occupied, trying nearby ports...`);
    for (let offset = 1; offset <= 10; offset++) {
        const portUp = preferredPort + offset;
        const portDown = preferredPort - offset;

        if (await isPortAvailable(portUp)) {
            logger.printInfoLog(`Using nearby port: ${portUp} (preferred was ${preferredPort})`);
            return portUp;
        }
        if (portDown > 1024 && (await isPortAvailable(portDown))) {
            logger.printInfoLog(`Using nearby port: ${portDown} (preferred was ${preferredPort})`);
            return portDown;
        }
    }

    // All ports in ±10 range are occupied
    throw new Error(`No available ports found in workspace-preferred range (${preferredPort - 10} to ${preferredPort + 10})`);
}

async function waitForServerReady(url: string, timeoutMs: number): Promise<boolean> {
    const start = Date.now();