@loucompanion/forge-bridge 0.1.3-dev.d46a8e73d03d → 0.1.3-dev.eeefdb0d19c1

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

@@ -0,0 +1,23 @@
+import type { LoadedHostRuntimeContract } from "./host-runtime-contract.js";
+export interface HostParallelPromotionRecord {
+    readonly schemaVersion: 1;
+    readonly repoId: string;
+    readonly runtimeContractFingerprint: string;
+    readonly runtimeContractSource?: "project" | "derived";
+    readonly observedAt: string;
+    readonly observedDispatchAttemptId: string;
+    readonly verifiedPortNames: readonly string[];
+}
+/** Persists only observed, contract-bound host parallel-safety evidence. */
+export declare class HostParallelPromotionStore {
+    private readonly stateRoot;
+    constructor(stateRoot: string);
+    load(repoId: string): Promise<HostParallelPromotionRecord | null>;
+    list(): Promise<readonly HostParallelPromotionRecord[]>;
+    observe(repoId: string, runtimeContract: LoadedHostRuntimeContract, dispatchAttemptId: string, verifiedPortNames: readonly string[]): Promise<HostParallelPromotionRecord>;
+    invalidate(repoId: string): Promise<void>;
+    private recordPath;
+}
+export declare function hostRuntimeContractFingerprint(runtimeContract: LoadedHostRuntimeContract): string;
+export declare function hostRuntimeParallelEligible(runtimeContract: LoadedHostRuntimeContract): boolean;
+export declare function configuredLaunchPortNames(runtimeContract: LoadedHostRuntimeContract): readonly string[];

package/dist/runtime/host-runtime-promotion.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+/** Persists only observed, contract-bound host parallel-safety evidence. */
+export class HostParallelPromotionStore {
+    stateRoot;
+    constructor(stateRoot) {
+        this.stateRoot = stateRoot;
+    }
+    async load(repoId) {
+        const normalizedRepoId = normalizeRepoId(repoId);
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.recordPath(normalizedRepoId), "utf8"));
+            return validRecord(parsed, normalizedRepoId) ? parsed : null;
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error instanceof SyntaxError)
+                return null;
+            throw error;
+        }
+    }
+    async list() {
+        const root = path.join(this.stateRoot, "runtime-promotion", "host");
+        let entries;
+        try {
+            entries = await fs.readdir(root);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const records = [];
+        for (const entry of entries.filter(value => /^[0-9a-f]{64}\.json$/u.test(value)).slice(0, 4096)) {
+            try {
+                const parsed = JSON.parse(await fs.readFile(path.join(root, entry), "utf8"));
+                const repoId = typeof parsed.repoId === "string" ? normalizeRepoId(parsed.repoId) : "";
+                if (repoId && validRecord(parsed, repoId))
+                    records.push(parsed);
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError))
+                    throw error;
+            }
+        }
+        return records.sort((left, right) => left.repoId.localeCompare(right.repoId));
+    }
+    async observe(repoId, runtimeContract, dispatchAttemptId, verifiedPortNames) {
+        if (!hostRuntimeParallelEligible(runtimeContract)) {
+            throw new Error("host_parallel_promotion_ineligible: the runtime contract is not eligible for parallel host execution.");
+        }
+        const requiredPorts = configuredLaunchPortNames(runtimeContract);
+        const observedPorts = [...new Set(verifiedPortNames)].sort((left, right) => left.localeCompare(right));
+        if (requiredPorts.length !== observedPorts.length
+            || requiredPorts.some((name, index) => name !== observedPorts[index])) {
+            throw new Error("host_parallel_promotion_unverified: every configured runtime listener must pass its assigned-port probe.");
+        }
+        const normalizedRepoId = normalizeRepoId(repoId);
+        const record = {
+            schemaVersion: 1,
+            repoId: normalizedRepoId,
+            runtimeContractFingerprint: hostRuntimeContractFingerprint(runtimeContract),
+            runtimeContractSource: runtimeContract.source === "project" ? "project" : "derived",
+            observedAt: new Date().toISOString(),
+            observedDispatchAttemptId: normalizedUuid(dispatchAttemptId, "dispatch attempt"),
+            verifiedPortNames: observedPorts,
+        };
+        const target = this.recordPath(normalizedRepoId);
+        const root = path.dirname(target);
+        await ensurePrivateDirectory(root);
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            const handle = await fs.open(temporary, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await fs.rename(temporary, target);
+            return record;
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async invalidate(repoId) {
+        await fs.rm(this.recordPath(normalizeRepoId(repoId)), { force: true });
+    }
+    recordPath(normalizedRepoId) {
+        const key = createHash("sha256").update(normalizedRepoId).digest("hex");
+        return path.join(this.stateRoot, "runtime-promotion", "host", `${key}.json`);
+    }
+}
+export function hostRuntimeContractFingerprint(runtimeContract) {
+    const canonical = JSON.stringify({
+        schemaVersion: runtimeContract.contract.schemaVersion,
+        runtime: runtimeContract.contract.runtime,
+        derivedCandidateFingerprint: runtimeContract.source === "derived"
+            ? runtimeContract.discovery?.candidateFingerprint ?? null
+            : null,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function hostRuntimeParallelEligible(runtimeContract) {
+    const runtime = runtimeContract.contract.runtime;
+    const launchedPorts = runtime.ports.filter(port => port.launch !== null);
+    return (runtimeContract.source === "project" || runtimeContract.source === "derived")
+        && runtime.hostConcurrency === "parallel"
+        && runtime.browserProfile === "isolated"
+        && runtime.singletonResources.length === 0
+        && launchedPorts.length > 0
+        && launchedPorts.length === runtime.ports.length
+        && launchedPorts.every(port => port.adapter !== null);
+}
+export function configuredLaunchPortNames(runtimeContract) {
+    return runtimeContract.contract.runtime.ports
+        .filter(port => port.launch !== null)
+        .map(port => port.name)
+        .sort((left, right) => left.localeCompare(right));
+}
+function validRecord(value, repoId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.schemaVersion === 1
+        && record.repoId === repoId
+        && /^sha256:[0-9a-f]{64}$/u.test(record.runtimeContractFingerprint ?? "")
+        && Number.isFinite(Date.parse(record.observedAt ?? ""))
+        && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(record.observedDispatchAttemptId ?? "")
+        && Array.isArray(record.verifiedPortNames)
+        && record.verifiedPortNames.length > 0
+        && record.verifiedPortNames.length <= 16
+        && record.verifiedPortNames.every(name => typeof name === "string" && /^[a-z][a-z0-9_-]{0,63}$/u.test(name));
+}
+function normalizeRepoId(repoId) {
+    const normalized = repoId.trim().toLowerCase();
+    if (!normalized || normalized.length > 512 || Array.from(normalized).some(character => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint < 32 || codePoint === 127;
+    })) {
+        throw new Error("host_parallel_promotion_invalid: repository identity is invalid.");
+    }
+    return normalized;
+}
+function normalizedUuid(value, label) {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(normalized)) {
+        throw new Error(`host_parallel_promotion_invalid: ${label} must be a full UUID.`);
+    }
+    return normalized;
+}
+async function ensurePrivateDirectory(target) {
+    await fs.mkdir(target, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await fs.chmod(target, 0o700);
+}

package/dist/runtime/node-host-runtime-adapter.d.ts

@@ -0,0 +1,51 @@
+import { HostPortBroker, type HostPortLaunch, type HostPortLeaseOwner, type HostPortReservation } from "./host-port-broker.js";
+import { type HostRuntimePortAdapter, type HostRuntimePortConfig } from "./host-runtime-contract.js";
+export type HostListenerOwnership = "unbound" | "owned" | "foreign";
+export interface NodeRuntimeCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly environment?: Readonly<Record<string, string>>;
+}
+export interface NodeRuntimeLaunchRequest extends NodeRuntimeCommand {
+    readonly framework: HostRuntimePortAdapter;
+    readonly port: HostPortReservation;
+    readonly baseUrl: string;
+}
+export interface NodeRuntimeCommandLauncher<T> {
+    readonly launch: (request: NodeRuntimeLaunchRequest, signal?: AbortSignal) => Promise<T>;
+    readonly inspectListener: (value: T, request: NodeRuntimeLaunchRequest, signal?: AbortSignal) => Promise<HostListenerOwnership>;
+    readonly readinessDiagnostics?: (value: T) => Promise<NodeRuntimeReadinessDiagnostics>;
+    readonly stop: (value: T) => Promise<void>;
+}
+export interface NodeRuntimeReadinessDiagnostics {
+    readonly exited: boolean;
+    readonly exitCode?: number;
+    readonly stdoutTail?: string;
+    readonly stderrTail?: string;
+}
+export interface NodeHostRuntimeAdapterOptions {
+    readonly readinessTimeoutMs?: number;
+    readonly readinessPollIntervalMs?: number;
+    readonly httpProbeTimeoutMs?: number;
+    readonly probeHttp?: (url: string, timeoutMs: number, signal?: AbortSignal) => Promise<boolean>;
+}
+export interface NodeRuntimeAdapterLaunch<T> extends HostPortLaunch<T> {
+    readonly request: NodeRuntimeLaunchRequest;
+}
+/**
+ * Launches an explicitly configured HTTP project command beneath the caller's
+ * attempt supervisor. It never shells a command and never promotes a project
+ * by framework detection alone.
+ */
+export declare class NodeHostRuntimeAdapter {
+    private readonly broker;
+    private readonly readinessTimeoutMs;
+    private readonly readinessPollIntervalMs;
+    private readonly httpProbeTimeoutMs;
+    private readonly probeHttp;
+    constructor(broker: HostPortBroker, options?: NodeHostRuntimeAdapterOptions);
+    launch<T>(owner: HostPortLeaseOwner, portConfig: HostRuntimePortConfig, command: NodeRuntimeCommand, launcher: NodeRuntimeCommandLauncher<T>, signal?: AbortSignal): Promise<NodeRuntimeAdapterLaunch<T>>;
+    private waitUntilReady;
+}
+export declare function buildNodeRuntimeLaunchRequest(framework: HostRuntimePortAdapter, portConfig: HostRuntimePortConfig, command: NodeRuntimeCommand, port: HostPortReservation): NodeRuntimeLaunchRequest;

package/dist/runtime/node-host-runtime-adapter.js

@@ -0,0 +1,268 @@
+import path from "node:path";
+import { hostPortEnvironment, } from "./host-runtime-contract.js";
+/**
+ * Launches an explicitly configured HTTP project command beneath the caller's
+ * attempt supervisor. It never shells a command and never promotes a project
+ * by framework detection alone.
+ */
+export class NodeHostRuntimeAdapter {
+    broker;
+    readinessTimeoutMs;
+    readinessPollIntervalMs;
+    httpProbeTimeoutMs;
+    probeHttp;
+    constructor(broker, options = {}) {
+        this.broker = broker;
+        this.readinessTimeoutMs = boundedInteger(options.readinessTimeoutMs ?? 120_000, 100, 120_000, "readinessTimeoutMs");
+        this.readinessPollIntervalMs = boundedInteger(options.readinessPollIntervalMs ?? 100, 10, 5_000, "readinessPollIntervalMs");
+        this.httpProbeTimeoutMs = boundedInteger(options.httpProbeTimeoutMs ?? 1_000, 50, 10_000, "httpProbeTimeoutMs");
+        this.probeHttp = options.probeHttp ?? probeHttpReadiness;
+    }
+    async launch(owner, portConfig, command, launcher, signal) {
+        const framework = portConfig.adapter;
+        if (framework !== "node" && framework !== "vite" && framework !== "next" && framework !== "aspnetcore") {
+            throw new Error("node_runtime_adapter_invalid: port config must explicitly select node, vite, next, or aspnetcore.");
+        }
+        validateCommand(command);
+        if (!portConfig.baseUrlEnv || !portConfig.format) {
+            throw new Error("node_runtime_adapter_invalid: an HTTP baseUrlEnv and loopback format are required.");
+        }
+        let activeRequest = null;
+        const launched = await this.broker.launchWithRetry(owner, {
+            name: portConfig.name,
+            protocol: "tcp",
+        }, {
+            launch: async (port, launchSignal) => {
+                const request = buildNodeRuntimeLaunchRequest(framework, portConfig, command, port);
+                activeRequest = request;
+                return await launcher.launch(request, launchSignal);
+            },
+            verifyOwnership: async (value, _port, verifySignal) => {
+                if (!activeRequest)
+                    throw new Error("node_runtime_adapter_state: launch request was not recorded.");
+                return await this.waitUntilReady(value, activeRequest, launcher, verifySignal);
+            },
+            stop: launcher.stop,
+        }, signal);
+        if (!activeRequest)
+            throw new Error("node_runtime_adapter_state: active launch request is missing.");
+        return { ...launched, request: activeRequest };
+    }
+    async waitUntilReady(value, request, launcher, signal) {
+        const deadline = Date.now() + this.readinessTimeoutMs;
+        let observedOwnership = "unbound";
+        while (Date.now() <= deadline) {
+            if (signal?.aborted)
+                throw cancellationError(signal);
+            const diagnostics = await launcher.readinessDiagnostics?.(value);
+            if (diagnostics?.exited) {
+                throw new Error(readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics));
+            }
+            const ownership = await launcher.inspectListener(value, request, signal);
+            observedOwnership = ownership;
+            if (ownership === "foreign")
+                return false;
+            if (ownership === "owned" && await this.probeHttp(request.baseUrl, this.httpProbeTimeoutMs, signal)) {
+                return true;
+            }
+            await wait(this.readinessPollIntervalMs, signal);
+        }
+        const diagnostics = await launcher.readinessDiagnostics?.(value);
+        if (diagnostics?.exited) {
+            throw new Error(readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics));
+        }
+        const code = observedOwnership === "owned"
+            ? "host_runtime_http_readiness_timeout"
+            : "host_runtime_listener_timeout";
+        const detail = observedOwnership === "owned"
+            ? `the supervised process owned its assigned loopback port but HTTP readiness did not succeed within ${this.readinessTimeoutMs}ms`
+            : `the supervised process did not bind its assigned loopback port within ${this.readinessTimeoutMs}ms`;
+        throw new Error(readinessFailure(code, detail, request, diagnostics));
+    }
+}
+function readinessFailure(code, detail, request, diagnostics) {
+    const evidence = [
+        boundedDiagnostic("stderr", diagnostics?.stderrTail),
+        boundedDiagnostic("stdout", diagnostics?.stdoutTail),
+    ].filter((value) => value !== null);
+    return `${code}: ${detail} (${request.baseUrl}).${evidence.length > 0 ? ` ${evidence.join(" ")}` : ""}`;
+}
+function boundedDiagnostic(label, value) {
+    const normalized = value?.replaceAll(/\s+/gu, " ").trim();
+    if (!normalized)
+        return null;
+    return `${label} tail: ${normalized.slice(-2_000)}`;
+}
+export function buildNodeRuntimeLaunchRequest(framework, portConfig, command, port) {
+    validateCommand(command);
+    if (port.hostIp !== "127.0.0.1" || port.protocol !== "tcp") {
+        throw new Error("node_runtime_adapter_invalid: project adapters require a TCP IPv4 loopback reservation.");
+    }
+    if (!portConfig.baseUrlEnv || !portConfig.format) {
+        throw new Error("node_runtime_adapter_invalid: an HTTP baseUrlEnv and loopback format are required.");
+    }
+    rejectConflictingFrameworkArguments(framework, command.args);
+    const portEnvironment = hostPortEnvironment(portConfig, port.hostIp, port.hostPort);
+    const baseUrl = portEnvironment[portConfig.baseUrlEnv];
+    if (!baseUrl)
+        throw new Error("node_runtime_adapter_invalid: base URL environment could not be rendered.");
+    const args = framework === "aspnetcore"
+        ? aspNetCoreArguments(command.command, command.args)
+        : [...command.args, ...frameworkArguments(framework, port.hostIp, port.hostPort)];
+    const adapterEnvironment = framework === "aspnetcore"
+        ? {
+            ASPNETCORE_URLS: baseUrl,
+            Hosting__Port: String(port.hostPort),
+            Harness__Reconciler__Hosted: "false",
+            Projects__RuntimeReadiness__Hosted: "false",
+            Runners__ServerLocalHeartbeat__Hosted: "false",
+            FORGE_RUNTIME_MODE: "host",
+            FORGE_DISPATCH_ATTEMPT_ID: port.dispatchAttemptId,
+            DOTNET_CLI_USE_MSBUILD_SERVER: "0",
+            DOTNET_NOLOGO: "1",
+        }
+        : { HOST: port.hostIp };
+    const forgeEnvironment = {
+        FORGE_RUNTIME_PORT_NAME: portConfig.name,
+        FORGE_RUNTIME_PORT: String(port.hostPort),
+        FORGE_RUNTIME_BASE_URL: baseUrl,
+    };
+    const expansionScope = {
+        ...command.environment,
+        ...portEnvironment,
+        ...adapterEnvironment,
+        ...forgeEnvironment,
+    };
+    return {
+        framework,
+        command: command.command,
+        args,
+        cwd: path.resolve(command.cwd),
+        environment: {
+            ...expandCommandEnvironment(command.environment, expansionScope),
+            ...portEnvironment,
+            ...adapterEnvironment,
+            ...forgeEnvironment,
+        },
+        port,
+        baseUrl,
+    };
+}
+function expandCommandEnvironment(environment, scope) {
+    return Object.fromEntries(Object.entries(environment ?? {}).map(([name, value]) => [
+        name,
+        value.replaceAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/gu, (_match, variable) => {
+            const resolved = scope[variable];
+            if (!resolved) {
+                throw new Error(`node_runtime_adapter_invalid: launch environment references unavailable variable '${variable}'.`);
+            }
+            return resolved;
+        }),
+    ]));
+}
+function frameworkArguments(framework, hostIp, hostPort) {
+    if (framework === "vite")
+        return ["--host", hostIp, "--port", String(hostPort), "--strictPort"];
+    if (framework === "next")
+        return ["--hostname", hostIp, "--port", String(hostPort)];
+    return [];
+}
+function rejectConflictingFrameworkArguments(framework, args) {
+    if (framework === "aspnetcore") {
+        const forbidden = new Set(["--urls", "--launch-profile", "-lp", "--no-launch-profile"]);
+        const conflict = args.find(argument => forbidden.has(argument)
+            || [...forbidden].some(flag => argument.startsWith(`${flag}=`)));
+        if (conflict) {
+            throw new Error(`node_runtime_adapter_invalid: command already supplies Forge-owned argument '${conflict}'.`);
+        }
+        return;
+    }
+    if (framework === "node")
+        return;
+    const forbidden = framework === "vite"
+        ? new Set(["--host", "--port", "--strictPort"])
+        : new Set(["--hostname", "--port", "-H", "-p"]);
+    const conflict = args.find(argument => forbidden.has(argument) || [...forbidden].some(flag => argument.startsWith(`${flag}=`)));
+    if (conflict) {
+        throw new Error(`node_runtime_adapter_invalid: command already supplies Forge-owned argument '${conflict}'.`);
+    }
+}
+function aspNetCoreArguments(command, args) {
+    const executable = path.basename(command).toLowerCase();
+    if (executable !== "dotnet" && executable !== "dotnet.exe") {
+        throw new Error("node_runtime_adapter_invalid: aspnetcore adapter requires the dotnet executable.");
+    }
+    if (args[0]?.toLowerCase() !== "run") {
+        throw new Error("node_runtime_adapter_invalid: aspnetcore adapter requires a dotnet run command.");
+    }
+    const applicationArguments = args.indexOf("--");
+    const insertionIndex = applicationArguments < 0 ? args.length : applicationArguments;
+    return [
+        ...args.slice(0, insertionIndex),
+        "--disable-build-servers",
+        "-p:UseSharedCompilation=false",
+        "-p:DefaultItemExcludesInProjectFolder=TestResults/**",
+        "--no-launch-profile",
+        ...args.slice(insertionIndex),
+    ];
+}
+function validateCommand(command) {
+    if (!boundedText(command.command, 1024)
+        || !path.isAbsolute(command.cwd)
+        || command.args.length > 128
+        || command.args.some(argument => !boundedText(argument, 4096))) {
+        throw new Error("node_runtime_adapter_invalid: command, arguments, or absolute working directory are invalid.");
+    }
+    for (const [name, value] of Object.entries(command.environment ?? {})) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u.test(name) || !boundedText(value, 8192)) {
+            throw new Error("node_runtime_adapter_invalid: command environment is invalid.");
+        }
+    }
+}
+async function probeHttpReadiness(url, timeoutMs, signal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    try {
+        const response = await fetch(url, { redirect: "manual", signal: combined });
+        await response.body?.cancel().catch(() => undefined);
+        return true;
+    }
+    catch (_error) {
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        return false;
+    }
+}
+function wait(milliseconds, signal) {
+    if (signal?.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, milliseconds);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(cancellationError(signal));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+function boundedInteger(value, minimum, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`node_runtime_adapter_invalid: ${name} must be between ${minimum} and ${maximum}.`);
+    }
+    return 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 ?? "Node runtime launch cancelled."));
+}

package/dist/runtime/playwright-host-runtime-adapter.d.ts

@@ -0,0 +1,20 @@
+import type { HostRuntimePlaywrightConfig } from "./host-runtime-contract.js";
+export interface PlaywrightHostRuntimeContext {
+    readonly worktreePath: string;
+    readonly temporaryDirectory: string;
+    readonly testOutputDirectory: string;
+    readonly browserProfileDirectory: string;
+    readonly baseUrl: string;
+}
+export interface PreparedPlaywrightHostRuntime {
+    readonly configPath: string;
+    readonly environment: Readonly<Record<string, string>>;
+}
+/**
+ * Prepares a finite Playwright test boundary for a managed-host attempt.
+ * The generated overlay points tests at Forge's verified listener, disables
+ * Playwright-managed web servers, and keeps writable artifacts attempt-local.
+ */
+export declare class PlaywrightHostRuntimeAdapter {
+    prepare(config: HostRuntimePlaywrightConfig, context: PlaywrightHostRuntimeContext): Promise<PreparedPlaywrightHostRuntime>;
+}