@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba7d36726eda

package/dist/runtime/host-listener-inspector.js

@@ -0,0 +1,185 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const windowsListenerOwnerPath = fileURLToPath(new URL("../../runtime/windows-listener-owner.ps1", import.meta.url));
+/** Proves that a loopback listener belongs to one exact supervised child. */
+export class HostListenerInspector {
+    commands;
+    platform;
+    constructor(commands = new ExecFileInspectionCommandRunner(), platform = process.platform) {
+        this.commands = commands;
+        this.platform = platform;
+    }
+    async inspect(child, reservation, owner) {
+        if (reservation.hostIp !== "127.0.0.1" || reservation.protocol !== "tcp") {
+            throw new Error("host_listener_inspection_invalid: only TCP IPv4 loopback listeners are supported.");
+        }
+        const metadata = await loadMetadata(child.metadataPath);
+        if (!metadata)
+            return "unbound";
+        if (!matchesOwner(metadata, child, owner))
+            return "foreign";
+        if (this.platform === "win32") {
+            return await this.inspectWindows(metadata.rootPid, reservation.hostPort);
+        }
+        return await this.inspectUnix(metadata.rootPid, reservation.hostPort);
+    }
+    async inspectWindows(rootPid, port) {
+        const netstat = await this.commands.run("netstat.exe", ["-ano", "-p", "TCP"]);
+        if (netstat.exitCode !== 0) {
+            throw commandError("netstat", netstat);
+        }
+        const listenerPids = parseWindowsListenerPids(netstat.stdout, port);
+        if (listenerPids.length === 0)
+            return "unbound";
+        const powershell = windowsPowerShellPath();
+        const ownership = await this.commands.run(powershell, [
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            windowsListenerOwnerPath,
+            "-RootProcessId",
+            String(rootPid),
+            "-ListenerProcessIds",
+            listenerPids.join(","),
+        ]);
+        if (ownership.exitCode !== 0)
+            throw commandError("Windows process ancestry", ownership);
+        let parsed;
+        try {
+            parsed = JSON.parse(ownership.stdout.trim());
+        }
+        catch (error) {
+            throw new Error("host_listener_inspection_failed: Windows ancestry output was invalid.", { cause: error });
+        }
+        const values = Array.isArray(parsed) ? parsed : [parsed];
+        return values.length === listenerPids.length && values.every(value => value === true) ? "owned" : "foreign";
+    }
+    async inspectUnix(rootPid, port) {
+        let listenerPids = null;
+        const lsof = await this.commands.run("lsof", [
+            "-nP",
+            "-a",
+            `-iTCP@127.0.0.1:${port}`,
+            "-sTCP:LISTEN",
+            "-Fp",
+        ]);
+        if (lsof.exitCode === 0 || lsof.exitCode === 1) {
+            listenerPids = parseLsofPids(lsof.stdout);
+        }
+        else if (lsof.errorCode !== "ENOENT") {
+            throw commandError("lsof", lsof);
+        }
+        if (listenerPids === null) {
+            const ss = await this.commands.run("ss", ["-H", "-ltnp", "sport", "=", `:${port}`]);
+            if (ss.exitCode !== 0)
+                throw commandError("ss", ss);
+            listenerPids = parseSsPids(ss.stdout, port);
+        }
+        if (listenerPids.length === 0)
+            return "unbound";
+        const processGroups = await this.commands.run("ps", [
+            "-o",
+            "pid=,pgid=",
+            "-p",
+            listenerPids.join(","),
+        ]);
+        if (processGroups.exitCode !== 0)
+            throw commandError("ps", processGroups);
+        const groups = parseProcessGroups(processGroups.stdout);
+        return listenerPids.every(pid => groups.get(pid) === rootPid) ? "owned" : "foreign";
+    }
+}
+export class ExecFileInspectionCommandRunner {
+    run(command, args) {
+        return new Promise(resolve => {
+            execFile(command, args, {
+                windowsHide: true,
+                timeout: 5_000,
+                maxBuffer: 4 * 1024 * 1024,
+            }, (error, stdout, stderr) => {
+                const processError = error;
+                resolve({
+                    exitCode: typeof processError?.code === "number" ? processError.code : error ? 1 : 0,
+                    stdout: String(stdout),
+                    stderr: String(stderr),
+                    ...(typeof processError?.code === "string" ? { errorCode: processError.code } : {}),
+                });
+            });
+        });
+    }
+}
+export function parseWindowsListenerPids(output, port) {
+    const suffix = `:${port}`;
+    const pids = output.split(/\r?\n/u).flatMap(line => {
+        const fields = line.trim().split(/\s+/u);
+        if (fields.length < 5 || fields[0]?.toUpperCase() !== "TCP" || fields[3]?.toUpperCase() !== "LISTENING")
+            return [];
+        if (fields[1] !== `127.0.0.1${suffix}`)
+            return [];
+        return validPid(fields[4]);
+    });
+    return uniqueSorted(pids);
+}
+export function parseLsofPids(output) {
+    return uniqueSorted(output.split(/\r?\n/u).flatMap(line => line.startsWith("p") ? validPid(line.slice(1)) : []));
+}
+export function parseSsPids(output, port) {
+    return uniqueSorted(output.split(/\r?\n/u).flatMap(line => {
+        if (!line.includes(`127.0.0.1:${port}`))
+            return [];
+        return [...line.matchAll(/pid=(\d+)/gu)].flatMap(match => validPid(match[1]));
+    }));
+}
+export function parseProcessGroups(output) {
+    const groups = new Map();
+    for (const line of output.split(/\r?\n/u)) {
+        const fields = line.trim().split(/\s+/u);
+        const pid = validPid(fields[0]);
+        const group = validPid(fields[1]);
+        if (pid.length === 1 && group.length === 1)
+            groups.set(pid[0], group[0]);
+    }
+    return groups;
+}
+async function loadMetadata(metadataPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+        if (parsed.schemaVersion !== 1 || !Number.isSafeInteger(parsed.rootPid) || parsed.rootPid <= 0) {
+            throw new Error("host_listener_inspection_invalid: process supervisor metadata is invalid.");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function matchesOwner(metadata, child, owner) {
+    return metadata.supervisorId === child.processSupervisorId
+        && metadata.runtimeLeaseId === owner.executionLeaseId
+        && metadata.dispatchAttemptId === owner.dispatchAttemptId
+        && metadata.fencingToken === owner.fencingToken;
+}
+function validPid(value) {
+    if (!value || !/^\d+$/u.test(value))
+        return [];
+    const pid = Number.parseInt(value, 10);
+    return Number.isSafeInteger(pid) && pid > 0 ? [pid] : [];
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left - right);
+}
+function commandError(label, result) {
+    const detail = result.stderr.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(0, 512);
+    return new Error(`host_listener_inspection_failed: ${label} exited ${result.exitCode}${detail ? `: ${detail}` : ""}.`);
+}
+function windowsPowerShellPath() {
+    const systemRoot = process.env.SystemRoot?.trim() || "C:\\Windows";
+    return path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}

package/dist/runtime/host-port-broker.d.ts

@@ -0,0 +1,76 @@
+import type { RuntimeIsolationPort } from "./runtime-isolation-lease.js";
+export interface HostPortLeaseOwner {
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly processSupervisorId: string;
+}
+export interface HostPortRequest {
+    readonly name: string;
+    readonly protocol?: "tcp";
+    readonly targetPort?: number;
+}
+export type HostPortReservationState = "reserved" | "handed_off" | "active";
+export interface HostPortReservation extends RuntimeIsolationPort, HostPortLeaseOwner {
+    readonly schemaVersion: 1;
+    readonly reservationId: string;
+    readonly state: HostPortReservationState;
+    readonly reservedAt: string;
+    readonly handedOffAt: string | null;
+    readonly activatedAt: string | null;
+}
+export interface HostPortLaunchLifecycle<T> {
+    readonly launch: (port: HostPortReservation, signal?: AbortSignal) => Promise<T>;
+    readonly verifyOwnership: (value: T, port: HostPortReservation, signal?: AbortSignal) => Promise<boolean>;
+    readonly stop: (value: T) => Promise<void>;
+}
+export interface HostPortLaunch<T> {
+    readonly reservation: HostPortReservation;
+    readonly value: T;
+}
+export interface HostPortBrokerOptions {
+    readonly hostIp?: "127.0.0.1";
+    readonly minimumPort?: number;
+    readonly maximumPort?: number;
+    readonly maximumLaunchAttempts?: number;
+}
+export interface HostPortBrokerDiagnostics {
+    readonly hostIp: "127.0.0.1";
+    readonly pool: {
+        readonly minimumPort: number;
+        readonly maximumPort: number;
+    } | null;
+    readonly reservations: readonly Omit<HostPortReservation, "fencingToken">[];
+}
+export declare class HostPortCollisionError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Owns runner-local loopback ports for supervised host attempts.
+ *
+ * A reservation keeps a real listening socket open until an adapter is ready to
+ * launch. The adapter then performs a narrow handoff and must prove that the
+ * supervised child owns the assigned endpoint before the reservation is active.
+ */
+export declare class HostPortBroker {
+    private readonly hostIp;
+    private readonly minimumPort;
+    private readonly maximumPort;
+    private readonly maximumLaunchAttempts;
+    private readonly reservations;
+    private readonly claimedPorts;
+    private nextPort;
+    private launchGate;
+    constructor(options?: HostPortBrokerOptions);
+    reserve(owner: HostPortLeaseOwner, request: HostPortRequest, signal?: AbortSignal): Promise<HostPortReservation>;
+    handoff(reservationId: string, owner: HostPortLeaseOwner): Promise<HostPortReservation | null>;
+    activate(reservationId: string, owner: HostPortLeaseOwner): HostPortReservation | null;
+    release(reservationId: string, owner: HostPortLeaseOwner): Promise<boolean>;
+    snapshot(): readonly HostPortReservation[];
+    diagnostics(): HostPortBrokerDiagnostics;
+    launchWithRetry<T>(owner: HostPortLeaseOwner, request: HostPortRequest, lifecycle: HostPortLaunchLifecycle<T>, signal?: AbortSignal): Promise<HostPortLaunch<T>>;
+    private reserveExcluding;
+    private listen;
+    private owned;
+    private withLaunchGate;
+}

package/dist/runtime/host-port-broker.js

@@ -0,0 +1,333 @@
+import { randomUUID } from "node:crypto";
+import net from "node:net";
+export class HostPortCollisionError extends Error {
+    constructor(message = "host_port_collision: the launched process did not own its assigned loopback port.") {
+        super(message);
+        this.name = "HostPortCollisionError";
+    }
+}
+/**
+ * Owns runner-local loopback ports for supervised host attempts.
+ *
+ * A reservation keeps a real listening socket open until an adapter is ready to
+ * launch. The adapter then performs a narrow handoff and must prove that the
+ * supervised child owns the assigned endpoint before the reservation is active.
+ */
+export class HostPortBroker {
+    hostIp;
+    minimumPort;
+    maximumPort;
+    maximumLaunchAttempts;
+    reservations = new Map();
+    claimedPorts = new Map();
+    nextPort;
+    launchGate = Promise.resolve();
+    constructor(options = {}) {
+        this.hostIp = options.hostIp ?? "127.0.0.1";
+        const hasMinimum = options.minimumPort !== undefined;
+        const hasMaximum = options.maximumPort !== undefined;
+        if (hasMinimum !== hasMaximum) {
+            throw new Error("host_port_broker_invalid: minimumPort and maximumPort must be configured together.");
+        }
+        this.minimumPort = hasMinimum ? validPort(options.minimumPort, "minimumPort") : null;
+        this.maximumPort = hasMaximum ? validPort(options.maximumPort, "maximumPort") : null;
+        if (this.minimumPort !== null && this.maximumPort !== null && this.minimumPort > this.maximumPort) {
+            throw new Error("host_port_broker_invalid: minimumPort cannot exceed maximumPort.");
+        }
+        this.maximumLaunchAttempts = options.maximumLaunchAttempts ?? 3;
+        if (!Number.isSafeInteger(this.maximumLaunchAttempts) || this.maximumLaunchAttempts < 1 || this.maximumLaunchAttempts > 10) {
+            throw new Error("host_port_broker_invalid: maximumLaunchAttempts must be between 1 and 10.");
+        }
+        this.nextPort = this.minimumPort;
+    }
+    async reserve(owner, request, signal) {
+        validateOwner(owner);
+        validateRequest(request);
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        const { server, port } = await this.listen(signal, new Set());
+        const now = new Date().toISOString();
+        const reservation = {
+            schemaVersion: 1,
+            reservationId: randomUUID(),
+            ...owner,
+            name: request.name,
+            protocol: "tcp",
+            hostIp: this.hostIp,
+            hostPort: port,
+            targetPort: request.targetPort ?? port,
+            state: "reserved",
+            reservedAt: now,
+            handedOffAt: null,
+            activatedAt: null,
+        };
+        this.reservations.set(reservation.reservationId, { reservation, server });
+        this.claimedPorts.set(port, reservation.reservationId);
+        return reservation;
+    }
+    async handoff(reservationId, owner) {
+        const held = this.owned(reservationId, owner);
+        if (!held || held.reservation.state !== "reserved")
+            return null;
+        await closeServer(held.server);
+        held.server = null;
+        held.reservation = {
+            ...held.reservation,
+            state: "handed_off",
+            handedOffAt: new Date().toISOString(),
+        };
+        return held.reservation;
+    }
+    activate(reservationId, owner) {
+        const held = this.owned(reservationId, owner);
+        if (!held || held.reservation.state !== "handed_off")
+            return null;
+        held.reservation = {
+            ...held.reservation,
+            state: "active",
+            activatedAt: new Date().toISOString(),
+        };
+        return held.reservation;
+    }
+    async release(reservationId, owner) {
+        const held = this.owned(reservationId, owner);
+        if (!held)
+            return false;
+        await closeServer(held.server);
+        this.reservations.delete(reservationId);
+        if (this.claimedPorts.get(held.reservation.hostPort) === reservationId) {
+            this.claimedPorts.delete(held.reservation.hostPort);
+        }
+        return true;
+    }
+    snapshot() {
+        return [...this.reservations.values()]
+            .map(entry => entry.reservation)
+            .sort((left, right) => left.hostPort - right.hostPort);
+    }
+    diagnostics() {
+        return {
+            hostIp: this.hostIp,
+            pool: this.minimumPort === null || this.maximumPort === null
+                ? null
+                : { minimumPort: this.minimumPort, maximumPort: this.maximumPort },
+            reservations: this.snapshot().map(({ fencingToken: _fencingToken, ...reservation }) => reservation),
+        };
+    }
+    async launchWithRetry(owner, request, lifecycle, signal) {
+        const rejectedPorts = new Set();
+        let lastCollision = null;
+        for (let attempt = 1; attempt <= this.maximumLaunchAttempts; attempt += 1) {
+            if (signal?.aborted)
+                throw cancellationError(signal);
+            const reservation = await this.reserveExcluding(owner, request, rejectedPorts, signal);
+            try {
+                return await this.withLaunchGate(async () => {
+                    let value;
+                    try {
+                        if (signal?.aborted)
+                            throw cancellationError(signal);
+                        const handedOff = await this.handoff(reservation.reservationId, owner);
+                        if (!handedOff)
+                            throw new Error("host_port_broker_state: reservation handoff failed.");
+                        value = await lifecycle.launch(handedOff, signal);
+                        if (!await lifecycle.verifyOwnership(value, handedOff, signal)) {
+                            throw new HostPortCollisionError();
+                        }
+                        const active = this.activate(reservation.reservationId, owner);
+                        if (!active)
+                            throw new Error("host_port_broker_state: reservation activation failed.");
+                        return { reservation: active, value };
+                    }
+                    catch (error) {
+                        if (value !== undefined)
+                            await lifecycle.stop(value).catch(() => undefined);
+                        rejectedPorts.add(reservation.hostPort);
+                        await this.release(reservation.reservationId, owner);
+                        throw error;
+                    }
+                }, signal);
+            }
+            catch (error) {
+                if (this.reservations.has(reservation.reservationId)) {
+                    rejectedPorts.add(reservation.hostPort);
+                    await this.release(reservation.reservationId, owner);
+                }
+                if (!(error instanceof HostPortCollisionError))
+                    throw error;
+                lastCollision = error;
+            }
+        }
+        throw lastCollision ?? new HostPortCollisionError("host_port_collision: launch retry budget exhausted.");
+    }
+    async reserveExcluding(owner, request, excludedPorts, signal) {
+        validateOwner(owner);
+        validateRequest(request);
+        const { server, port } = await this.listen(signal, excludedPorts);
+        const now = new Date().toISOString();
+        const reservation = {
+            schemaVersion: 1,
+            reservationId: randomUUID(),
+            ...owner,
+            name: request.name,
+            protocol: "tcp",
+            hostIp: this.hostIp,
+            hostPort: port,
+            targetPort: request.targetPort ?? port,
+            state: "reserved",
+            reservedAt: now,
+            handedOffAt: null,
+            activatedAt: null,
+        };
+        this.reservations.set(reservation.reservationId, { reservation, server });
+        this.claimedPorts.set(port, reservation.reservationId);
+        return reservation;
+    }
+    async listen(signal, excludedPorts) {
+        if (this.minimumPort === null || this.maximumPort === null) {
+            for (let attempt = 0; attempt < 16; attempt += 1) {
+                const result = await listenOn(this.hostIp, 0, signal);
+                if (!this.claimedPorts.has(result.port) && !excludedPorts.has(result.port))
+                    return result;
+                await closeServer(result.server);
+            }
+            throw new Error("host_port_broker_exhausted: could not reserve a unique ephemeral loopback port.");
+        }
+        const poolSize = this.maximumPort - this.minimumPort + 1;
+        for (let attempt = 0; attempt < poolSize; attempt += 1) {
+            const port = this.nextPort ?? this.minimumPort;
+            this.nextPort = port >= this.maximumPort ? this.minimumPort : port + 1;
+            if (this.claimedPorts.has(port) || excludedPorts.has(port))
+                continue;
+            try {
+                return await listenOn(this.hostIp, port, signal);
+            }
+            catch (error) {
+                if (isAddressInUse(error))
+                    continue;
+                throw error;
+            }
+        }
+        throw new Error("host_port_broker_exhausted: no loopback ports are available in the configured pool.");
+    }
+    owned(reservationId, owner) {
+        const held = this.reservations.get(reservationId);
+        if (!held)
+            return null;
+        return sameOwner(held.reservation, owner) ? held : null;
+    }
+    async withLaunchGate(action, signal) {
+        const predecessor = this.launchGate;
+        let release = () => undefined;
+        const turn = new Promise(resolve => { release = resolve; });
+        this.launchGate = predecessor.then(() => turn, () => turn);
+        try {
+            await waitForTurn(predecessor, signal);
+        }
+        catch (error) {
+            void predecessor.finally(release);
+            throw error;
+        }
+        try {
+            return await action();
+        }
+        finally {
+            release();
+        }
+    }
+}
+function listenOn(host, port, signal) {
+    if (signal?.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const server = net.createServer(socket => socket.destroy());
+        const abort = () => {
+            server.close();
+            reject(cancellationError(signal));
+        };
+        const error = (cause) => {
+            signal?.removeEventListener("abort", abort);
+            reject(cause);
+        };
+        server.once("error", error);
+        signal?.addEventListener("abort", abort, { once: true });
+        server.listen({ host, port, exclusive: true }, () => {
+            signal?.removeEventListener("abort", abort);
+            server.removeListener("error", error);
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                void closeServer(server).then(() => reject(new Error("host_port_broker_invalid: listener address was unavailable.")));
+                return;
+            }
+            resolve({ server, port: address.port });
+        });
+    });
+}
+function closeServer(server) {
+    if (!server?.listening)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+}
+function validateOwner(owner) {
+    if (![owner.dispatchAttemptId, owner.executionLeaseId, owner.fencingToken].every(isUuid)
+        || !boundedText(owner.processSupervisorId, 255)) {
+        throw new Error("host_port_broker_invalid: owner identity or fence is invalid.");
+    }
+}
+function validateRequest(request) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/u.test(request.name)
+        || (request.protocol !== undefined && request.protocol !== "tcp")) {
+        throw new Error("host_port_broker_invalid: only named TCP loopback reservations are supported.");
+    }
+    if (request.targetPort !== undefined)
+        validPort(request.targetPort, "targetPort");
+}
+function validPort(value, label) {
+    if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 65535) {
+        throw new Error(`host_port_broker_invalid: ${label} must be a valid TCP port.`);
+    }
+    return Number(value);
+}
+function sameOwner(left, right) {
+    return left.dispatchAttemptId === right.dispatchAttemptId
+        && left.executionLeaseId === right.executionLeaseId
+        && left.fencingToken === right.fencingToken
+        && left.processSupervisorId === right.processSupervisorId;
+}
+function isAddressInUse(error) {
+    return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value);
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every(character => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function cancellationError(signal) {
+    return new Error(String(signal?.reason ?? "Host port reservation cancelled."));
+}
+function waitForTurn(predecessor, signal) {
+    if (!signal)
+        return predecessor;
+    if (signal.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            reject(cancellationError(signal));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        void predecessor.then(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, error => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}

package/dist/runtime/host-runtime-contract.d.ts

@@ -0,0 +1,39 @@
+export declare const hostRuntimeContractPath = ".forge/forge.runtime.yml";
+export type RequestedHostConcurrency = "serial" | "parallel" | "disabled";
+export type HostRuntimePortAdapter = "node" | "vite" | "next" | "aspnetcore";
+export interface HostRuntimeLaunchConfig {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly workingDirectory: string;
+}
+export interface HostRuntimePortConfig {
+    readonly name: string;
+    readonly adapter: HostRuntimePortAdapter | null;
+    readonly launch: HostRuntimeLaunchConfig | null;
+    readonly env: string;
+    readonly baseUrlEnv: string | null;
+    readonly format: string | null;
+}
+export interface HostRuntimePlaywrightConfig {
+    readonly config: string;
+    readonly baseUrlPort: string;
+    readonly workers: number;
+}
+export interface HostRuntimeContract {
+    readonly schemaVersion: 1;
+    readonly runtime: {
+        readonly hostConcurrency: RequestedHostConcurrency;
+        readonly ports: readonly HostRuntimePortConfig[];
+        readonly playwright: HostRuntimePlaywrightConfig | null;
+        readonly browserProfile: "isolated";
+        readonly singletonResources: readonly string[];
+    };
+}
+export interface LoadedHostRuntimeContract {
+    readonly contract: HostRuntimeContract;
+    readonly source: "default" | "project";
+}
+export declare function loadHostRuntimeContract(worktreePath: string): Promise<LoadedHostRuntimeContract>;
+export declare function defaultHostRuntimeContract(): HostRuntimeContract;
+export declare function validateHostRuntimeContract(source: string): HostRuntimeContract;
+export declare function hostPortEnvironment(config: HostRuntimePortConfig, hostIp: "127.0.0.1", hostPort: number): Readonly<Record<string, string>>;