@undefineds.co/xpod 0.4.15 → 0.4.16

package/dist/runtime/ingress-occupant.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identifyIngressPortOccupants = identifyIngressPortOccupants;
+exports.describeOccupants = describeOccupants;
+const node_child_process_1 = require("node:child_process");
+/**
+ * Names every process listening on the port.
+ *
+ * `lsof` is the portable answer on macOS and most Linux images; `ss` covers Linux hosts
+ * without lsof. When neither is available the answer is "an unidentified listener", never a
+ * silent success.
+ */
+function identifyIngressPortOccupants(port, deps = {}) {
+    const exec = deps.exec ?? defaultExec;
+    const pids = new Set();
+    let probeFailure;
+    try {
+        for (const pid of parseLsofPids(exec('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fp']))) {
+            pids.add(pid);
+        }
+    }
+    catch (error) {
+        probeFailure = `lsof: ${error.message}`;
+    }
+    if (pids.size === 0) {
+        try {
+            for (const pid of parseSsPids(exec('ss', ['-ltnpH', `sport = :${port}`]))) {
+                pids.add(pid);
+            }
+        }
+        catch (error) {
+            probeFailure = probeFailure
+                ? `${probeFailure}; ss: ${error.message}`
+                : `ss: ${error.message}`;
+        }
+    }
+    const occupants = [...pids].map((pid) => describeProcess(pid, exec));
+    return {
+        port,
+        occupants,
+        description: describeOccupants(port, occupants, probeFailure),
+    };
+}
+/** One line for an operator: pid, command, cwd and start time of everything on the port. */
+function describeOccupants(port, occupants, probeFailure) {
+    if (occupants.length === 0) {
+        return probeFailure
+            ? `port ${port} is not bindable and no process could be named (${probeFailure})`
+            : `port ${port} is not bindable and no listener reports it (a transient bind conflict)`;
+    }
+    return occupants.map((occupant) => {
+        const parts = [
+            `pid ${occupant.pid}`,
+            occupant.command || 'command unknown',
+            occupant.cwd ? `cwd ${occupant.cwd}` : undefined,
+            occupant.startedAt ? `started ${occupant.startedAt}` : undefined,
+        ].filter(Boolean);
+        return parts.join(' · ');
+    }).join('; ');
+}
+function defaultExec(file, args) {
+    return (0, node_child_process_1.execFileSync)(file, [...args], { encoding: 'utf8', timeout: 15_000 });
+}
+function parseLsofPids(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('p'))
+        .map((line) => Number.parseInt(line.slice(1), 10))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+function parseSsPids(output) {
+    const pids = new Set();
+    for (const match of output.matchAll(/pid=(\d+)/gu)) {
+        const pid = Number.parseInt(match[1], 10);
+        if (Number.isInteger(pid) && pid > 0) {
+            pids.add(pid);
+        }
+    }
+    return [...pids];
+}
+function describeProcess(pid, exec) {
+    let command = '';
+    let startedAt;
+    try {
+        const line = exec('ps', ['-o', 'lstart=,command=', '-p', String(pid)]).trim();
+        // `lstart` is a fixed 24-character timestamp ("Mon Sep 22 17:28:46 2026"), so the command
+        // starts right after it; anything shorter is a bare command line.
+        const stamp = /^[A-Z][a-z]{2} [A-Z][a-z]{2} {1,2}\d{1,2} \d{2}:\d{2}:\d{2} \d{4}\s+/u.exec(line);
+        if (stamp) {
+            startedAt = stamp[0].trim();
+            command = line.slice(stamp[0].length).trim();
+        }
+        else {
+            command = line;
+        }
+    }
+    catch {
+        // The process may have exited between the port probe and this call.
+    }
+    let cwd;
+    try {
+        const line = exec('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn']).trim();
+        cwd = line.split('\n').find((entry) => entry.startsWith('n'))?.slice(1).trim() || undefined;
+    }
+    catch {
+        // cwd is optional evidence.
+    }
+    return { pid, command, ...(cwd ? { cwd } : {}), ...(startedAt ? { startedAt } : {}) };
+}
+//# sourceMappingURL=ingress-occupant.js.map

package/dist/runtime/ingress-port.d.ts

@@ -0,0 +1,89 @@
+import { type DeclaredOriginReadResult } from '../tunnel/TunnelDeclaredOrigin';
+/**
+ * Where the tunnel entry (the listener every remote forwarder terminates on) is bound.
+ *
+ * Order, strictest first:
+ *   1. an explicit `XPOD_GATEWAY_INGRESS_PORT` — an operator or harness pin is never overridden
+ *      and never silently moved to another port;
+ *   2. the port the *active* profile's provider console already declares (SakuraFrp
+ *      `GET /v4/tunnels` `local_port`; the Cloudflare dashboard's remote configuration read
+ *      back through the connector) — adopted when it is free, so the operator does not have to
+ *      edit the console to match the runtime;
+ *   3. `findGatewayIngressPort(gatewayPort)` — the predictable, dynamic gateway+3..+9 entry.
+ *
+ * Both strict sources are strict about *being taken*: a port somebody else holds fails the
+ * start with the occupant named (pid, command line, cwd). Nothing here signals a process, and
+ * nothing silently falls back — a tunnel that forwards to a number must never find a different
+ * process listening on it.
+ */
+export type IngressPortSource = 'explicit' | 'console-declared' | 'gateway-default';
+export interface IngressProfileLike {
+    id: string;
+    provider: string;
+    credentialEnvKey?: string;
+    credentialConfigured?: boolean;
+}
+/** A port a provider console declares for this runtime's origin. */
+export interface IngressPortDeclaration {
+    profileId: string;
+    provider: string;
+    port: number;
+    readBack: string;
+    scheme?: string;
+}
+export interface IngressPortResolution {
+    port: number;
+    source: IngressPortSource;
+    /** The active profile's declaration that was adopted, when there was one. */
+    declared?: IngressPortDeclaration;
+    /**
+     * Declarations from profiles that are *not* active.
+     *
+     * They are reported because two profiles naming different ports is exactly the confusion
+     * this resolution exists to end; only the active one may decide the listener.
+     */
+    inactiveDeclarations: IngressPortDeclaration[];
+}
+export interface IngressPortLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+export interface IngressPortDeps {
+    findDefaultPort(mainPort: number): Promise<number>;
+    isFree(port: number): Promise<boolean>;
+    identifyOccupants(port: number): string;
+    readDeclaredOrigin(profile: IngressProfileLike, options: {
+        env: Record<string, string | undefined>;
+        active: boolean;
+    }): Promise<DeclaredOriginReadResult>;
+    logger: IngressPortLogger;
+}
+export interface IngressPortRequest {
+    mainPort: number;
+    env?: Record<string, string | undefined>;
+    profiles?: readonly IngressProfileLike[];
+    activeProfileId?: string;
+    /** Service ports this run serves (gateway/CSS/API): never a valid tunnel origin. */
+    reservedPorts?: Iterable<number>;
+    deps?: Partial<IngressPortDeps>;
+}
+/** A strict port that could not be taken: the occupant is named, and nothing was signalled. */
+export declare class IngressPortConflictError extends Error {
+    readonly port: number;
+    readonly occupant: string;
+    constructor(port: number, occupant: string);
+}
+export declare function defaultIngressPortDeps(): IngressPortDeps;
+/**
+ * Validates a port that came from outside this runtime (an operator pin or a console).
+ *
+ * Zero, out-of-range and privileged ports are refused with the reason spelled out: binding
+ * them either fails later with a bare errno, or needs privileges the runtime should not hold.
+ */
+export declare function assertUsableIngressPort(port: number, options: {
+    label: string;
+    reservedPorts?: ReadonlySet<number>;
+}): void;
+/** Reads the explicit pin strictly: present but malformed is an error, not an absent value. */
+export declare function parseExplicitIngressPort(raw: string | undefined): number | undefined;
+export declare function resolveIngressPort(request: IngressPortRequest): Promise<IngressPortResolution>;

package/dist/runtime/ingress-port.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngressPortConflictError = void 0;
+exports.defaultIngressPortDeps = defaultIngressPortDeps;
+exports.assertUsableIngressPort = assertUsableIngressPort;
+exports.parseExplicitIngressPort = parseExplicitIngressPort;
+exports.resolveIngressPort = resolveIngressPort;
+const global_logger_factory_1 = require("global-logger-factory");
+const port_finder_1 = require("./port-finder");
+const ingress_occupant_1 = require("./ingress-occupant");
+const TunnelDeclaredOrigin_1 = require("../tunnel/TunnelDeclaredOrigin");
+const TunnelProviderCatalog_1 = require("../tunnel/TunnelProviderCatalog");
+/** A strict port that could not be taken: the occupant is named, and nothing was signalled. */
+class IngressPortConflictError extends Error {
+    constructor(port, occupant) {
+        super(`tunnel entry port ${port} is already in use by ${occupant}`);
+        this.port = port;
+        this.occupant = occupant;
+        this.name = 'IngressPortConflictError';
+    }
+}
+exports.IngressPortConflictError = IngressPortConflictError;
+function defaultIngressPortDeps() {
+    const logger = (0, global_logger_factory_1.getLoggerFor)('IngressPort');
+    return {
+        findDefaultPort: port_finder_1.findGatewayIngressPort,
+        isFree: port_finder_1.isFreePortForWildcard,
+        identifyOccupants: (port) => (0, ingress_occupant_1.identifyIngressPortOccupants)(port).description,
+        readDeclaredOrigin: async (profile, options) => await (0, TunnelDeclaredOrigin_1.readDeclaredIngressOrigin)(profile, {
+            env: options.env,
+            active: options.active,
+        }),
+        logger: {
+            info: (message) => logger.info(message),
+            warn: (message) => logger.warn(message),
+        },
+    };
+}
+/**
+ * Validates a port that came from outside this runtime (an operator pin or a console).
+ *
+ * Zero, out-of-range and privileged ports are refused with the reason spelled out: binding
+ * them either fails later with a bare errno, or needs privileges the runtime should not hold.
+ */
+function assertUsableIngressPort(port, options) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new Error(`${options.label} is not a usable port (expected 1-65535); `
+            + 'a tunnel origin has to be a real port number');
+    }
+    if (port < 1024) {
+        throw new Error(`${options.label} is a privileged port (1-1023); this runtime does not take root `
+            + 'to bind a tunnel origin, so point the tunnel at a port at or above 1024');
+    }
+    if (options.reservedPorts?.has(port)) {
+        throw new Error(`${options.label} is a port this runtime already serves (gateway/CSS/API); `
+            + 'the tunnel entry has to be its own listener, or forwarded traffic would land on another service');
+    }
+}
+/** Reads the explicit pin strictly: present but malformed is an error, not an absent value. */
+function parseExplicitIngressPort(raw) {
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(trimmed)) {
+        throw new Error(`XPOD_GATEWAY_INGRESS_PORT="${trimmed}" is not a valid port number (expected 1-65535)`);
+    }
+    return Number.parseInt(trimmed, 10);
+}
+async function resolveIngressPort(request) {
+    const deps = { ...defaultIngressPortDeps(), ...request.deps };
+    const env = request.env ?? process.env;
+    const reservedPorts = new Set(request.reservedPorts ?? []);
+    const profiles = request.profiles ?? [];
+    const activeProfileId = request.activeProfileId?.trim();
+    const active = activeProfileId && activeProfileId !== 'none'
+        ? profiles.find((profile) => profile.id === activeProfileId)
+        : undefined;
+    const explicit = parseExplicitIngressPort(env.XPOD_GATEWAY_INGRESS_PORT);
+    if (explicit !== undefined) {
+        assertUsableIngressPort(explicit, {
+            label: `XPOD_GATEWAY_INGRESS_PORT=${explicit}`,
+            reservedPorts,
+        });
+        await requireFree(explicit, `XPOD_GATEWAY_INGRESS_PORT=${explicit}`, deps);
+        deps.logger.info(`Tunnel entry pinned to ${explicit} by XPOD_GATEWAY_INGRESS_PORT `
+            + '(a provider console value is not read while an explicit pin is present)');
+        return { port: explicit, source: 'explicit', inactiveDeclarations: [] };
+    }
+    const inactiveDeclarations = await readInactiveConsoleDeclarations({ profiles, active, env, deps });
+    for (const declaration of inactiveDeclarations) {
+        deps.logger.warn(`profile ${declaration.profileId} (${declaration.provider}) is not active, but its console declares `
+            + `tunnel origin ${declaration.port} (${declaration.readBack}); `
+            + `the active profile is ${active?.id ?? 'none'}, so its entry decides this runtime's listener`);
+    }
+    const activeDescriptor = active ? (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(active.provider) : undefined;
+    if (active && activeDescriptor?.originOwner === 'console') {
+        const read = await deps.readDeclaredOrigin(active, { env, active: true });
+        if (read.origin) {
+            const label = `the ${activeDescriptor.label} console's declared tunnel origin ${read.origin.port}`;
+            assertUsableIngressPort(read.origin.port, { label, reservedPorts });
+            await requireFree(read.origin.port, label, deps);
+            if (read.origin.scheme && read.origin.scheme !== 'http') {
+                deps.logger.warn(`${activeDescriptor.label} declares the origin as ${read.origin.scheme}://localhost:${read.origin.port}, `
+                    + `but this runtime's tunnel entry speaks plain HTTP; the port is adopted, the scheme is not `
+                    + '(terminate TLS in the provider, or point the console at http://)');
+            }
+            deps.logger.info(`Adopting the ${activeDescriptor.label} console's tunnel origin ${read.origin.port} `
+                + `(${read.origin.readBack}); the operator does not have to edit the console`);
+            return {
+                port: read.origin.port,
+                source: 'console-declared',
+                declared: {
+                    profileId: active.id,
+                    provider: activeDescriptor.id,
+                    port: read.origin.port,
+                    readBack: read.origin.readBack,
+                    ...(read.origin.scheme ? { scheme: read.origin.scheme } : {}),
+                },
+                inactiveDeclarations,
+            };
+        }
+        // The console owns the number, so the runtime cannot invent a different one and still be
+        // reachable. The declaration is unreadable here, which is reported loudly; an explicit pin
+        // (handled above) is the deterministic way out.
+        deps.logger.warn(`the ${activeDescriptor.label} console's tunnel origin could not be read `
+            + `(${read.error ?? 'no reason reported'}); this runtime will serve the default tunnel entry `
+            + 'instead, and the tunnel provider will report its own failure. '
+            + 'Pin XPOD_GATEWAY_INGRESS_PORT to decide the entry explicitly');
+    }
+    const port = await deps.findDefaultPort(request.mainPort);
+    deps.logger.info(`Tunnel entry ${port} chosen from the gateway port ${request.mainPort} (gateway+3..+9, first free port)`);
+    return { port, source: 'gateway-default', inactiveDeclarations };
+}
+/** A strict port is taken as-is or not at all; the occupant is named, never signalled. */
+async function requireFree(port, label, deps) {
+    if (await deps.isFree(port)) {
+        return;
+    }
+    const occupant = deps.identifyOccupants(port);
+    throw new IngressPortConflictError(port, occupant);
+}
+async function readInactiveConsoleDeclarations(input) {
+    const declarations = [];
+    for (const profile of input.profiles) {
+        if (profile.id === input.active?.id) {
+            continue;
+        }
+        if ((0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(profile.provider)?.originOwner !== 'console') {
+            continue;
+        }
+        const read = await input.deps.readDeclaredOrigin(profile, { env: input.env, active: false });
+        if (read.origin) {
+            declarations.push({
+                profileId: profile.id,
+                provider: profile.provider,
+                port: read.origin.port,
+                readBack: read.origin.readBack,
+                ...(read.origin.scheme ? { scheme: read.origin.scheme } : {}),
+            });
+        }
+    }
+    return declarations;
+}
+//# sourceMappingURL=ingress-port.js.map

package/dist/runtime/oidc-issuer.d.ts

@@ -11,4 +11,13 @@ export declare const DEFAULT_LOCAL_OIDC_ISSUER = "https://id.undefineds.co/";
  */
 export declare function resolveExternalOidcIssuer(env: RuntimeEnv): string | undefined;
 export declare function oidcTokenEndpoint(issuer: string): string;
+/**
+ * Whether an issuer only this machine could serve.
+ *
+ * An explicit `SOLID_OIDC_ISSUER` may be loopback on purpose (a developer running their own IdP
+ * next to the runtime). A *remembered* issuer is different: nothing in this process serves it, so
+ * a loopback value there can only be residue from an older run - and adopting it sends every
+ * login to a port with no listener.
+ */
+export declare function isLoopbackIssuer(issuer: string | undefined): boolean;
 export declare function cloudApiEndpointFromIssuer(issuer: string): string;

package/dist/runtime/oidc-issuer.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_LOCAL_OIDC_ISSUER = exports.OIDC_ISSUER_ENV_KEYS = void 0;
 exports.resolveExternalOidcIssuer = resolveExternalOidcIssuer;
 exports.oidcTokenEndpoint = oidcTokenEndpoint;
+exports.isLoopbackIssuer = isLoopbackIssuer;
 exports.cloudApiEndpointFromIssuer = cloudApiEndpointFromIssuer;
 exports.OIDC_ISSUER_ENV_KEYS = [
     'SOLID_OIDC_ISSUER',
@@ -32,6 +33,28 @@ function resolveExternalOidcIssuer(env) {
 function oidcTokenEndpoint(issuer) {
     return `${issuer.replace(/\/+$/u, '')}/.oidc/token`;
 }
+/**
+ * Whether an issuer only this machine could serve.
+ *
+ * An explicit `SOLID_OIDC_ISSUER` may be loopback on purpose (a developer running their own IdP
+ * next to the runtime). A *remembered* issuer is different: nothing in this process serves it, so
+ * a loopback value there can only be residue from an older run - and adopting it sends every
+ * login to a port with no listener.
+ */
+function isLoopbackIssuer(issuer) {
+    const value = issuer?.trim();
+    if (!value) {
+        return false;
+    }
+    try {
+        const host = new URL(value).hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+        // A literal in 127.0.0.0/8, not any host that merely starts with "127.".
+        return host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/u.test(host);
+    }
+    catch {
+        return false;
+    }
+}
 function cloudApiEndpointFromIssuer(issuer) {
     const identity = new URL(issuer);
     return identity.origin === 'https://id.undefineds.co'

package/dist/runtime/port-finder.d.ts

@@ -5,8 +5,20 @@
  * into a provider console and it survives restarts - while staying clear of the block a
  * neighbouring runtime plans for its own services. When the neighbourhood is busy the caller
  * gets an OS-assigned port instead of a stolen one; the runtime reports whichever it got.
+ *
+ * Reserved ports are skipped here too: a group that needs a fixed port has published a
+ * reservation, and a dynamic entry that took it would break that group's tunnel instead of
+ * merely moving its own listener.
  */
 export declare function findGatewayIngressPort(gatewayPort: number): Promise<number>;
+/**
+ * The first free port at or above `basePort`.
+ *
+ * Reserved ports are skipped, not merely avoided by convention: a group that needs a fixed port
+ * (the tunnel acceptance's console-owned 5737) publishes a reservation, and every allocator -
+ * the runtime, the test helpers, the integration runners - goes around it instead of racing for
+ * it. That is the difference between "usually fine" and "cannot collide".
+ */
 export declare function getFreePort(basePort: number, host?: string, timeoutMs?: number): Promise<number>;
 /**
  * Loopback port handed out by the OS for a listener that must not collide with ports the
@@ -19,10 +31,16 @@ export declare function getFreePort(basePort: number, host?: string, timeoutMs?:
  */
 export declare function getEphemeralLoopbackPort(): Promise<number>;
 /**
- * Allocates a port for child services that bind wildcard addresses.
- * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost
- * can miss an occupied port on the other address family.
+ * Whether this runtime could take the port as-is, on both address families.
+ *
+ * A tunnel origin is bound on the wildcard address, so a listener on `*:<port>` owns the
+ * number even when IPv4 loopback alone still looks free.
+ *
+ * This is a probe, not an allocation: it answers about the socket, so a *reserved* port that is
+ * genuinely free answers `true` (the group that reserved it still has to bind it). The
+ * `getFreePort*` family is the allocating one, and it skips reserved ports.
  */
+export declare function isFreePortForWildcard(port: number, timeoutMs?: number): Promise<boolean>;
 /**
  * Takes exactly this port or fails.
  *
@@ -30,4 +48,10 @@ export declare function getEphemeralLoopbackPort(): Promise<number>;
  * scans upward, which would leave the runtime listening somewhere the tunnel never reaches.
  */
 export declare function requireFreePortForWildcard(port: number, timeoutMs?: number): Promise<number>;
+/**
+ * Allocates a port for child services that bind wildcard addresses.
+ *
+ * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost can miss an
+ * occupied port on the other address family - and a reserved port is skipped either way.
+ */
 export declare function getFreePortForWildcard(basePort: number, timeoutMs?: number): Promise<number>;

package/dist/runtime/port-finder.js

@@ -6,10 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.findGatewayIngressPort = findGatewayIngressPort;
 exports.getFreePort = getFreePort;
 exports.getEphemeralLoopbackPort = getEphemeralLoopbackPort;
+exports.isFreePortForWildcard = isFreePortForWildcard;
 exports.requireFreePortForWildcard = requireFreePortForWildcard;
 exports.getFreePortForWildcard = getFreePortForWildcard;
 const node_net_1 = __importDefault(require("node:net"));
 const node_os_1 = __importDefault(require("node:os"));
+const port_reservations_1 = require("./port-reservations");
 const HIGHEST_PORT = 65_535;
 const PORT_PROBE_TIMEOUT_MS = 1_000;
 const RETRYABLE_PORT_ERRORS = new Set([
@@ -107,6 +109,10 @@ async function canListen(port, host, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
  * into a provider console and it survives restarts - while staying clear of the block a
  * neighbouring runtime plans for its own services. When the neighbourhood is busy the caller
  * gets an OS-assigned port instead of a stolen one; the runtime reports whichever it got.
+ *
+ * Reserved ports are skipped here too: a group that needs a fixed port has published a
+ * reservation, and a dynamic entry that took it would break that group's tunnel instead of
+ * merely moving its own listener.
  */
 async function findGatewayIngressPort(gatewayPort) {
     for (let offset = 3; offset < 10; offset += 1) {
@@ -117,8 +123,20 @@ async function findGatewayIngressPort(gatewayPort) {
     }
     return await getEphemeralLoopbackPort();
 }
+/**
+ * The first free port at or above `basePort`.
+ *
+ * Reserved ports are skipped, not merely avoided by convention: a group that needs a fixed port
+ * (the tunnel acceptance's console-owned 5737) publishes a reservation, and every allocator -
+ * the runtime, the test helpers, the integration runners - goes around it instead of racing for
+ * it. That is the difference between "usually fine" and "cannot collide".
+ */
 async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+    const reserved = (0, port_reservations_1.reservedPorts)();
     for (let port = basePort; port <= HIGHEST_PORT; port++) {
+        if (reserved.has(port)) {
+            continue;
+        }
         if (await canListen(port, host, timeoutMs)) {
             return port;
         }
@@ -135,30 +153,35 @@ async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_
  * runtime's service.
  */
 async function getEphemeralLoopbackPort() {
-    return await new Promise((resolve, reject) => {
-        const server = node_net_1.default.createServer();
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const address = server.address();
-            const port = typeof address === 'object' && address ? address.port : 0;
-            server.close((error) => {
-                if (error) {
-                    reject(error);
-                    return;
-                }
-                resolve(port);
-            });
-        });
-    });
+    // One retry rule for "the OS does not know about reservations", shared with the fixtures that
+    // bind their own server (`listenOnUnreservedPort`).
+    return await (0, port_reservations_1.getUnreservedEphemeralPort)('127.0.0.1');
 }
 function hasIpv6Address() {
     return Object.values(node_os_1.default.networkInterfaces()).some((entries) => entries?.some((entry) => entry.family === 'IPv6'));
 }
 /**
- * Allocates a port for child services that bind wildcard addresses.
- * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost
- * can miss an occupied port on the other address family.
+ * Whether this runtime could take the port as-is, on both address families.
+ *
+ * A tunnel origin is bound on the wildcard address, so a listener on `*:<port>` owns the
+ * number even when IPv4 loopback alone still looks free.
+ *
+ * This is a probe, not an allocation: it answers about the socket, so a *reserved* port that is
+ * genuinely free answers `true` (the group that reserved it still has to bind it). The
+ * `getFreePort*` family is the allocating one, and it skips reserved ports.
  */
+async function isFreePortForWildcard(port, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        return false;
+    }
+    if (!await canListen(port, '0.0.0.0', timeoutMs)) {
+        return false;
+    }
+    if (hasIpv6Address() && !await canListen(port, '::', timeoutMs)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Takes exactly this port or fails.
  *
@@ -169,17 +192,24 @@ async function requireFreePortForWildcard(port, timeoutMs = PORT_PROBE_TIMEOUT_M
     if (!Number.isInteger(port) || port <= 0 || port > 65535) {
         throw new Error(`ingress port ${port} is not a valid port number`);
     }
-    if (!await canListen(port, '0.0.0.0', timeoutMs)) {
+    if (!await isFreePortForWildcard(port, timeoutMs)) {
         throw new Error(`ingress port ${port} is already in use; free it or point the tunnel at another port`);
     }
-    if (hasIpv6Address() && !await canListen(port, '::', timeoutMs)) {
-        throw new Error(`ingress port ${port} is already in use on IPv6; free it or point the tunnel at another port`);
-    }
     return port;
 }
+/**
+ * Allocates a port for child services that bind wildcard addresses.
+ *
+ * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost can miss an
+ * occupied port on the other address family - and a reserved port is skipped either way.
+ */
 async function getFreePortForWildcard(basePort, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
     const probeIpv6 = hasIpv6Address();
+    const reserved = (0, port_reservations_1.reservedPorts)();
     for (let port = basePort; port <= HIGHEST_PORT; port++) {
+        if (reserved.has(port)) {
+            continue;
+        }
         if (!await canListen(port, '0.0.0.0', timeoutMs)) {
             continue;
         }