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

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

@@ -0,0 +1,1241 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { StreamingProviderProcessRunner, } from "../session/provider-cli/provider-cli.process.js";
+import { createRuntimeIsolationLease, renewRuntimeIsolationLease, transitionRuntimeIsolationLease, validRuntimeIsolationLease, withRuntimeIsolationResources, } from "./runtime-isolation-lease.js";
+import { hostPortEnvironment, loadHostRuntimeContract, } from "./host-runtime-contract.js";
+import { HostPortBroker, } from "./host-port-broker.js";
+import { NodeHostRuntimeAdapter, } from "./node-host-runtime-adapter.js";
+import { AttemptProcessSupervisorRegistry } from "./attempt-process-supervisor-registry.js";
+import { AttemptNodeRuntimeLauncher } from "./attempt-node-runtime-launcher.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import { PlaywrightHostRuntimeAdapter } from "./playwright-host-runtime-adapter.js";
+import { HostParallelPromotionStore, configuredLaunchPortNames, hostRuntimeContractFingerprint, hostRuntimeParallelEligible, } from "./host-runtime-promotion.js";
+import { ExactHostProcessRecovery, } from "../shared/process/host-process-recovery.js";
+export class HostRuntimeLeaseManager {
+    stateRoot;
+    processSupervisors;
+    processRunner;
+    listenerInspector;
+    promotionStore;
+    playwrightAdapter;
+    processRecovery;
+    active = new Map();
+    pendingRenewals = new Map();
+    admissions = new Map();
+    singletonOwners = new Map();
+    singletonWaiters = [];
+    parallelProjectOwners = new Map();
+    parallelProjectWaiters = [];
+    degraded = new Map();
+    portBroker;
+    nodeAdapter;
+    constructor(stateRoot, portBroker = new HostPortBroker(), nodeAdapter, processSupervisors = new AttemptProcessSupervisorRegistry(), processRunner = new StreamingProviderProcessRunner(), listenerInspector = new HostListenerInspector(), promotionStore = new HostParallelPromotionStore(stateRoot), playwrightAdapter = new PlaywrightHostRuntimeAdapter(), processRecovery = new ExactHostProcessRecovery()) {
+        this.stateRoot = stateRoot;
+        this.processSupervisors = processSupervisors;
+        this.processRunner = processRunner;
+        this.listenerInspector = listenerInspector;
+        this.promotionStore = promotionStore;
+        this.playwrightAdapter = playwrightAdapter;
+        this.processRecovery = processRecovery;
+        this.portBroker = portBroker;
+        this.nodeAdapter = nodeAdapter ?? new NodeHostRuntimeAdapter(portBroker);
+    }
+    async reap(options) {
+        const report = {
+            examined: 0,
+            reaped: 0,
+            processesTerminated: 0,
+            reusedPidsProtected: 0,
+            degraded: 0,
+        };
+        for (const ledger of await this.readLedgers()) {
+            const lease = ledger.runtimeLease;
+            if (lease.runnerId !== options.runnerId || this.active.has(lease.dispatchAttemptId))
+                continue;
+            const staleInstance = lease.runnerInstanceId !== options.runnerInstanceId;
+            const expired = Date.parse(lease.expiresAt) <= (options.nowMs ?? Date.now());
+            if (!staleInstance && !expired && lease.state !== "released" && lease.state !== "degraded")
+                continue;
+            report.examined += 1;
+            const attemptRoot = this.attemptRoot(lease.dispatchAttemptId);
+            let outcomes;
+            try {
+                outcomes = await this.recoverPersistedProcesses(lease, attemptRoot);
+            }
+            catch {
+                await this.markLedgerDegraded(ledger);
+                report.degraded += 1;
+                continue;
+            }
+            report.processesTerminated += outcomes.filter(outcome => outcome === "terminated").length;
+            report.reusedPidsProtected += outcomes.filter(outcome => outcome === "pid_reused").length;
+            if (outcomes.includes("unverifiable")) {
+                await this.markLedgerDegraded(ledger);
+                report.degraded += 1;
+                continue;
+            }
+            try {
+                const releasing = transitionHostLeaseForCleanup(lease, "releasing");
+                await this.writeLedger(releasing, ledger.repoId);
+                await fs.rm(attemptRoot, { recursive: true, force: true });
+                await fs.rm(this.ledgerPath(lease.dispatchAttemptId), { force: true });
+                this.forgetDegraded(lease.dispatchAttemptId, lease.fencingToken);
+                report.reaped += 1;
+            }
+            catch {
+                await this.markLedgerDegraded(ledger);
+                report.degraded += 1;
+            }
+        }
+        return report;
+    }
+    snapshot() {
+        const projects = new Map();
+        for (const [dispatchAttemptId, admission] of this.admissions) {
+            const active = this.active.get(dispatchAttemptId);
+            const project = capacityProject(projects, admission.repoId);
+            if (active) {
+                if (active.lease.state === "degraded") {
+                    project.degradedAttempts += 1;
+                    project.safetyClass = conservativeSafetyClass(project.safetyClass, "host_serial_only");
+                }
+                else {
+                    project.activeAttempts += 1;
+                    const effectiveConcurrency = effectiveHostConcurrency(active.lease, active.runtimeContract);
+                    project.safetyClass = conservativeSafetyClass(project.safetyClass, effectiveConcurrency === "host_parallel_safe"
+                        ? effectiveConcurrency
+                        : admission.parallelProjectKey && admission.provisionalPromotionFingerprint
+                            ? "host_parallel_candidate"
+                            : "host_serial_only");
+                }
+            }
+            else {
+                project.reservedAttempts += 1;
+                project.safetyClass = conservativeSafetyClass(project.safetyClass, admission.provisionalPromotionFingerprint ? "host_parallel_candidate" : "host_serial_only");
+            }
+        }
+        for (const [dispatchAttemptId, degraded] of this.degraded) {
+            if (this.active.has(dispatchAttemptId) || !degraded.repoId)
+                continue;
+            const project = capacityProject(projects, degraded.repoId);
+            project.degradedAttempts += 1;
+            project.safetyClass = conservativeSafetyClass(project.safetyClass, "host_serial_only");
+        }
+        for (const waiter of this.singletonWaiters) {
+            const repoId = repoIdFromProjectSingletonKeys(waiter.keys);
+            if (!repoId)
+                continue;
+            const project = capacityProject(projects, repoId);
+            project.waitingAttempts += 1;
+            project.safetyClass = conservativeSafetyClass(project.safetyClass, "host_serial_only");
+        }
+        for (const waiter of this.parallelProjectWaiters) {
+            const repoId = repoIdFromProjectSingletonKey(waiter.key);
+            if (!repoId)
+                continue;
+            const project = capacityProject(projects, repoId);
+            project.waitingAttempts += 1;
+            project.safetyClass = conservativeSafetyClass(project.safetyClass, "host_parallel_candidate");
+        }
+        const activeAttempts = [...this.active.values()]
+            .filter(active => active.lease.state !== "degraded").length;
+        const degradedAttempts = new Set([
+            ...this.degraded.keys(),
+            ...[...this.active.entries()]
+                .filter(([, active]) => active.lease.state === "degraded")
+                .map(([dispatchAttemptId]) => dispatchAttemptId),
+        ]).size;
+        return {
+            activeAttempts,
+            reservedAttempts: Math.max(0, this.admissions.size - this.active.size),
+            waitingAttempts: this.singletonWaiters.length + this.parallelProjectWaiters.length,
+            degradedAttempts,
+            exclusiveReservations: this.singletonOwners.size,
+            sharedReservations: [...this.parallelProjectOwners.values()]
+                .reduce((count, owners) => count + owners.size, 0),
+            projects: [...projects.values()]
+                .map(project => ({
+                ...project,
+                safetyClass: project.safetyClass ?? "host_serial_only",
+            }))
+                .sort((left, right) => left.repoId.localeCompare(right.repoId)),
+        };
+    }
+    async acquire(dispatch, signal) {
+        const sandbox = dispatch.sandbox;
+        if (!sandbox || sandbox.executionMode !== "host") {
+            throw new Error("host_runtime_lease_invalid: managed host sandbox context is required.");
+        }
+        uuidHex(sandbox.dispatchAttemptId, "dispatch attempt");
+        uuidHex(dispatch.lease.fencingToken, "fencing token");
+        const owner = {
+            dispatchAttemptId: sandbox.dispatchAttemptId,
+            fencingToken: dispatch.lease.fencingToken,
+        };
+        const existing = this.admissions.get(sandbox.dispatchAttemptId);
+        if (existing) {
+            if (existing.fencingToken !== owner.fencingToken) {
+                throw new Error("host_runtime_singleton_conflict: dispatch attempt already holds admission under a different fence.");
+            }
+            return existing.keys;
+        }
+        const promotion = await this.promotionStore.load(dispatch.repo.id);
+        const projectKey = projectHostRuntimeSingletonKey(dispatch.repo.id);
+        const keys = promotion ? [] : [projectKey];
+        const expiresAt = this.pendingRenewals.get(sandbox.dispatchAttemptId)?.fencingToken === owner.fencingToken
+            ? this.pendingRenewals.get(sandbox.dispatchAttemptId).expiresAt
+            : dispatch.lease.expiresAt;
+        try {
+            if (promotion) {
+                await this.reserveParallelProject(projectKey, owner, expiresAt, signal);
+            }
+            else {
+                await this.reserveSingletonKeys(keys, owner, expiresAt, signal);
+            }
+        }
+        catch (error) {
+            this.clearPendingRenewal(owner);
+            throw error;
+        }
+        this.admissions.set(sandbox.dispatchAttemptId, {
+            repoId: dispatch.repo.id,
+            fencingToken: owner.fencingToken,
+            provisionalPromotionFingerprint: promotion?.runtimeContractFingerprint ?? null,
+            keys,
+            parallelProjectKey: promotion ? projectKey : null,
+        });
+        return keys;
+    }
+    async reserveSingletonKeys(keys, owner, expiresAt, signal) {
+        const owned = keys.every(key => sameSingletonOwner(this.singletonOwners.get(key), owner));
+        if (owned)
+            return;
+        const staleFence = [...this.singletonOwners.values()].find(existing => existing.dispatchAttemptId === owner.dispatchAttemptId
+            && existing.fencingToken !== owner.fencingToken);
+        if (staleFence) {
+            throw new Error("host_runtime_singleton_conflict: dispatch attempt already holds the singleton under a different fence.");
+        }
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        throwIfAdmissionExpired(expiresAt);
+        if (this.singletonKeysAvailable(keys)) {
+            this.assignSingletonKeys(keys, owner);
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = {
+                owner,
+                keys,
+                resolve: () => resolve(),
+                reject,
+                signal,
+                expiresAt,
+                deadlineTimer: null,
+                abort: () => {
+                    const index = this.singletonWaiters.indexOf(waiter);
+                    if (index >= 0)
+                        this.singletonWaiters.splice(index, 1);
+                    clearAdmissionDeadline(waiter);
+                    this.clearPendingRenewal(owner);
+                    reject(cancellationError(signal));
+                    this.drainAdmissionWaiters();
+                },
+                expire: () => {
+                    const index = this.singletonWaiters.indexOf(waiter);
+                    if (index < 0)
+                        return;
+                    this.singletonWaiters.splice(index, 1);
+                    clearAdmissionDeadline(waiter);
+                    waiter.signal?.removeEventListener("abort", waiter.abort);
+                    this.clearPendingRenewal(owner);
+                    reject(new HostRuntimeAdmissionExpiredError());
+                    this.drainAdmissionWaiters();
+                },
+            };
+            this.singletonWaiters.push(waiter);
+            signal?.addEventListener("abort", waiter.abort, { once: true });
+            waiter.deadlineTimer = scheduleAdmissionDeadline(waiter.expiresAt, waiter.expire);
+            this.drainAdmissionWaiters();
+        });
+    }
+    async reserveParallelProject(key, owner, expiresAt, signal) {
+        if (this.parallelProjectOwned(key, owner))
+            return;
+        const staleFence = [...(this.parallelProjectOwners.get(key)?.values() ?? [])]
+            .find(existing => existing.dispatchAttemptId === owner.dispatchAttemptId
+            && existing.fencingToken !== owner.fencingToken);
+        if (staleFence) {
+            throw new Error("host_runtime_parallel_conflict: dispatch attempt already holds shared admission under a different fence.");
+        }
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        throwIfAdmissionExpired(expiresAt);
+        if (this.parallelProjectAvailable(key)) {
+            this.assignParallelProject(key, owner);
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = {
+                owner,
+                key,
+                resolve,
+                reject,
+                signal,
+                expiresAt,
+                deadlineTimer: null,
+                abort: () => {
+                    const index = this.parallelProjectWaiters.indexOf(waiter);
+                    if (index >= 0)
+                        this.parallelProjectWaiters.splice(index, 1);
+                    clearAdmissionDeadline(waiter);
+                    this.clearPendingRenewal(owner);
+                    reject(cancellationError(signal));
+                    this.drainAdmissionWaiters();
+                },
+                expire: () => {
+                    const index = this.parallelProjectWaiters.indexOf(waiter);
+                    if (index < 0)
+                        return;
+                    this.parallelProjectWaiters.splice(index, 1);
+                    clearAdmissionDeadline(waiter);
+                    waiter.signal?.removeEventListener("abort", waiter.abort);
+                    this.clearPendingRenewal(owner);
+                    reject(new HostRuntimeAdmissionExpiredError());
+                    this.drainAdmissionWaiters();
+                },
+            };
+            this.parallelProjectWaiters.push(waiter);
+            signal?.addEventListener("abort", waiter.abort, { once: true });
+            waiter.deadlineTimer = scheduleAdmissionDeadline(waiter.expiresAt, waiter.expire);
+            this.drainAdmissionWaiters();
+        });
+    }
+    async start(dispatch, worktreePath, signal) {
+        const sandbox = dispatch.sandbox;
+        if (!sandbox || sandbox.executionMode !== "host") {
+            throw new Error("host_runtime_lease_invalid: managed host sandbox context is required.");
+        }
+        const existing = this.active.get(sandbox.dispatchAttemptId);
+        if (existing) {
+            if (existing.lease.fencingToken !== dispatch.lease.fencingToken) {
+                throw new Error("host_runtime_lease_conflict: an active host lease has a different fence.");
+            }
+            return {
+                lease: existing.lease,
+                environment: hostRuntimeEnvironment(dispatch.session.id, existing.lease, existing.runtimeContract),
+                runtimeContract: existing.runtimeContract,
+            };
+        }
+        const admission = this.admissions.get(sandbox.dispatchAttemptId);
+        const owner = { dispatchAttemptId: sandbox.dispatchAttemptId, fencingToken: dispatch.lease.fencingToken };
+        if (!admission || admission.fencingToken !== owner.fencingToken) {
+            throw new Error("host_runtime_singleton_unreserved: managed host admission is required before start.");
+        }
+        const attemptHex = uuidHex(sandbox.dispatchAttemptId, "dispatch attempt");
+        const normalizedWorktreePath = path.resolve(worktreePath);
+        const attemptRoot = path.join(this.stateRoot, "host-attempts", attemptHex);
+        const temporaryPath = path.join(attemptRoot, "tmp");
+        const logPath = path.join(attemptRoot, "logs");
+        const cachePath = path.join(attemptRoot, "cache");
+        const browserProfilePath = path.join(attemptRoot, "browser-profile");
+        const testOutputPath = path.join(attemptRoot, "test-output");
+        const processSupervisorMetadataPath = path.join(logPath, "attempt-process-supervisor.json");
+        const processSupervisorId = `host-${attemptHex}`;
+        const renewedExpiry = this.pendingRenewals.get(sandbox.dispatchAttemptId);
+        const expiresAt = renewedExpiry?.fencingToken === dispatch.lease.fencingToken
+            ? renewedExpiry.expiresAt
+            : dispatch.lease.expiresAt;
+        let processSupervisor = null;
+        try {
+            let runtimeContract;
+            try {
+                runtimeContract = await loadHostRuntimeContract(normalizedWorktreePath);
+            }
+            catch (error) {
+                if (admission.provisionalPromotionFingerprint) {
+                    await this.promotionStore.invalidate(dispatch.repo.id).catch(() => undefined);
+                }
+                throw error;
+            }
+            if (runtimeContract.contract.runtime.hostConcurrency === "disabled") {
+                throw new Error("host_runtime_disabled: project runtime configuration requires Docker execution.");
+            }
+            const runtimeContractFingerprint = hostRuntimeContractFingerprint(runtimeContract);
+            const promotion = await this.promotionStore.load(dispatch.repo.id);
+            const promotionMatches = hostRuntimeParallelEligible(runtimeContract)
+                && promotion?.runtimeContractFingerprint === runtimeContractFingerprint;
+            if (admission.keys.length === 0 && !promotionMatches) {
+                await this.promotionStore.invalidate(dispatch.repo.id);
+                const projectKeys = hostRuntimeSingletonKeys(dispatch);
+                if (admission.parallelProjectKey) {
+                    this.releaseParallelProjectNoDrain(admission.parallelProjectKey, owner);
+                    admission.parallelProjectKey = null;
+                }
+                const expiresAt = this.pendingRenewals.get(sandbox.dispatchAttemptId)?.fencingToken === owner.fencingToken
+                    ? this.pendingRenewals.get(sandbox.dispatchAttemptId).expiresAt
+                    : dispatch.lease.expiresAt;
+                await this.reserveSingletonKeys(projectKeys, owner, expiresAt, signal);
+                admission.keys = projectKeys;
+            }
+            const singletonKeys = admission.keys;
+            if (!singletonKeys.every(key => sameSingletonOwner(this.singletonOwners.get(key), owner))) {
+                throw new Error("host_runtime_singleton_unreserved: managed host singleton ownership is required before start.");
+            }
+            if (admission.parallelProjectKey && !this.parallelProjectOwned(admission.parallelProjectKey, owner)) {
+                throw new Error("host_runtime_parallel_unreserved: matching shared project admission is required before start.");
+            }
+            await Promise.all([
+                ensurePrivateDirectory(temporaryPath),
+                ensurePrivateDirectory(logPath),
+                ensurePrivateDirectory(cachePath),
+                ensurePrivateDirectory(browserProfilePath),
+                ensurePrivateDirectory(testOutputPath),
+            ]);
+            let lease = createRuntimeIsolationLease({
+                leaseId: sandbox.executionLeaseId,
+                dispatchAttemptId: sandbox.dispatchAttemptId,
+                executionLeaseId: sandbox.executionLeaseId,
+                fencingToken: dispatch.lease.fencingToken,
+                runnerId: dispatch.execution.runnerId ?? "",
+                runnerInstanceId: sandbox.runnerInstanceId,
+                worktreeKey: dispatch.lease.worktreeKey,
+                worktreePath: normalizedWorktreePath,
+                mode: "host",
+                expiresAt,
+                resources: {
+                    memoryReservationBytes: 0,
+                    cpuMillis: 0,
+                    pids: 0,
+                    ports: [],
+                    paths: [
+                        { path: normalizedWorktreePath, role: "worktree" },
+                        { path: temporaryPath, role: "temporary" },
+                        { path: logPath, role: "logs" },
+                        { path: cachePath, role: "cache" },
+                        { path: browserProfilePath, role: "browser_profile" },
+                        { path: testOutputPath, role: "test_output" },
+                        { path: processSupervisorMetadataPath, role: "process_supervisor_metadata" },
+                    ],
+                    processSupervisorId,
+                    dockerResources: [],
+                    singletonKeys,
+                },
+            });
+            await this.writeLedger(lease);
+            lease = transitionRuntimeIsolationLease(lease, "starting");
+            await this.writeLedger(lease);
+            lease = transitionRuntimeIsolationLease(lease, "active");
+            await this.writeLedger(lease);
+            processSupervisor = this.processSupervisors.register({
+                processSupervisorId,
+                dispatchAttemptId: lease.dispatchAttemptId,
+                executionLeaseId: lease.executionLeaseId,
+                fencingToken: lease.fencingToken,
+                logDirectory: logPath,
+            }, this.processRunner, { signal });
+            this.active.set(sandbox.dispatchAttemptId, {
+                lease,
+                repoId: dispatch.repo.id,
+                sessionId: dispatch.session.id,
+                attemptRoot,
+                runtimeContract,
+                runtimeContractFingerprint,
+                parallelPromotionEligible: hostRuntimeParallelEligible(runtimeContract),
+                processSupervisor,
+                adapterCleanups: [],
+                pendingAdapterLaunches: new Map(),
+                releasing: false,
+            });
+            this.pendingRenewals.delete(sandbox.dispatchAttemptId);
+            return {
+                lease,
+                environment: hostRuntimeEnvironment(dispatch.session.id, lease, runtimeContract),
+                runtimeContract,
+            };
+        }
+        catch (error) {
+            this.pendingRenewals.delete(sandbox.dispatchAttemptId);
+            if (processSupervisor) {
+                await processSupervisor.stopAll(dispatch.lease.fencingToken, "Host runtime start rolled back.").catch(() => undefined);
+                this.processSupervisors.unregister(sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+            }
+            await fs.rm(attemptRoot, { recursive: true, force: true }).catch(() => undefined);
+            await fs.rm(this.ledgerPath(sandbox.dispatchAttemptId), { force: true }).catch(() => undefined);
+            this.releaseSingletonKeys(sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+            this.releaseParallelProjects(sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+            this.deleteAdmission(sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+            throw error;
+        }
+    }
+    async updateLease(dispatchAttemptId, fencingToken, expiresAt) {
+        try {
+            uuidHex(dispatchAttemptId, "dispatch attempt");
+            uuidHex(fencingToken, "fencing token");
+        }
+        catch {
+            return;
+        }
+        const active = this.active.get(dispatchAttemptId);
+        if (!active) {
+            if (Number.isFinite(Date.parse(expiresAt))) {
+                const pending = this.pendingRenewals.get(dispatchAttemptId);
+                if (!pending
+                    || pending.fencingToken !== fencingToken
+                    || Date.parse(expiresAt) > Date.parse(pending.expiresAt)) {
+                    this.pendingRenewals.set(dispatchAttemptId, { fencingToken, expiresAt });
+                }
+                this.renewAdmissionWaiterDeadline(dispatchAttemptId, fencingToken, expiresAt);
+            }
+            return;
+        }
+        const renewed = renewRuntimeIsolationLease(active.lease, fencingToken, expiresAt);
+        if (!renewed)
+            return;
+        active.lease = renewed;
+        await this.writeLedger(renewed);
+    }
+    async startConfiguredProject(dispatchAttemptId, fencingToken, signal) {
+        const active = this.active.get(dispatchAttemptId);
+        if (!active || active.lease.fencingToken !== fencingToken || active.lease.state !== "active" || active.releasing) {
+            throw new Error("host_runtime_project_unavailable: an active matching host runtime lease is required.");
+        }
+        const configuredPort = active.runtimeContract.contract.runtime.ports.find(port => port.launch !== null);
+        if (!configuredPort?.launch) {
+            return {
+                lease: active.lease,
+                environment: hostRuntimeEnvironment(active.sessionId, active.lease, active.runtimeContract),
+                runtimeContract: active.runtimeContract,
+            };
+        }
+        const workingDirectory = await containedWorkingDirectory(active.lease.worktreePath, configuredPort.launch.workingDirectory);
+        const owner = hostPortOwner(active.lease);
+        const logDirectory = active.lease.resources.paths.find(entry => entry.role === "logs")?.path;
+        if (!logDirectory)
+            throw new Error("host_runtime_project_invalid: attempt log directory is unavailable.");
+        const launcher = new AttemptNodeRuntimeLauncher(active.processSupervisor, owner, logDirectory, this.listenerInspector);
+        const launched = await this.launchNodeRuntime(dispatchAttemptId, fencingToken, configuredPort.name, {
+            command: configuredPort.launch.command,
+            args: configuredPort.launch.args,
+            cwd: workingDirectory,
+            environment: hostRuntimeEnvironment(active.sessionId, active.lease, active.runtimeContract),
+        }, launcher, signal);
+        const promotedLease = await this.promoteVerifiedRuntime(active, launched.runtimeLease);
+        const runtimeEnvironment = hostRuntimeEnvironment(active.sessionId, promotedLease, active.runtimeContract);
+        const playwright = active.runtimeContract.contract.runtime.playwright;
+        if (!playwright) {
+            return {
+                lease: promotedLease,
+                environment: runtimeEnvironment,
+                runtimeContract: active.runtimeContract,
+            };
+        }
+        const playwrightPort = promotedLease.resources.ports.find(port => port.name === playwright.baseUrlPort);
+        const playwrightPortConfig = active.runtimeContract.contract.runtime.ports
+            .find(port => port.name === playwright.baseUrlPort);
+        if (!playwrightPort || !playwrightPortConfig?.baseUrlEnv) {
+            throw new Error("host_runtime_playwright_unavailable: the configured verified base URL is unavailable.");
+        }
+        if (playwrightPort.hostIp !== "127.0.0.1") {
+            throw new Error("host_runtime_playwright_unavailable: Playwright requires an IPv4 loopback listener.");
+        }
+        const baseUrl = hostPortEnvironment(playwrightPortConfig, playwrightPort.hostIp, playwrightPort.hostPort)[playwrightPortConfig.baseUrlEnv];
+        if (!baseUrl)
+            throw new Error("host_runtime_playwright_unavailable: the configured base URL could not be rendered.");
+        const pathFor = (role) => promotedLease.resources.paths.find(entry => entry.role === role)?.path ?? "";
+        const preparedPlaywright = await this.playwrightAdapter.prepare(playwright, {
+            worktreePath: promotedLease.worktreePath,
+            temporaryDirectory: pathFor("temporary"),
+            testOutputDirectory: pathFor("test_output"),
+            browserProfileDirectory: pathFor("browser_profile"),
+            baseUrl,
+        });
+        return {
+            lease: promotedLease,
+            environment: { ...runtimeEnvironment, ...preparedPlaywright.environment },
+            runtimeContract: active.runtimeContract,
+        };
+    }
+    async promoteVerifiedRuntime(active, runtimeLease) {
+        if (!active.parallelPromotionEligible)
+            return runtimeLease;
+        const verifiedPortNames = runtimeLease.resources.ports.map(port => port.name).sort((left, right) => left.localeCompare(right));
+        const requiredPortNames = configuredLaunchPortNames(active.runtimeContract);
+        if (requiredPortNames.length !== verifiedPortNames.length
+            || requiredPortNames.some((name, index) => name !== verifiedPortNames[index])) {
+            return runtimeLease;
+        }
+        const projectKey = projectHostRuntimeSingletonKey(active.repoId);
+        const promotedLease = withRuntimeIsolationResources(runtimeLease, {
+            ...runtimeLease.resources,
+            singletonKeys: runtimeLease.resources.singletonKeys.filter(key => key !== projectKey),
+        });
+        await this.writeLedger(promotedLease);
+        active.lease = promotedLease;
+        try {
+            const promotion = await this.promotionStore.observe(active.repoId, active.runtimeContract, runtimeLease.dispatchAttemptId, verifiedPortNames);
+            this.convertSingletonToParallelProject(projectKey, {
+                dispatchAttemptId: runtimeLease.dispatchAttemptId,
+                fencingToken: runtimeLease.fencingToken,
+            });
+            const admission = this.admissions.get(runtimeLease.dispatchAttemptId);
+            if (admission?.fencingToken === runtimeLease.fencingToken) {
+                this.admissions.set(runtimeLease.dispatchAttemptId, {
+                    ...admission,
+                    keys: promotedLease.resources.singletonKeys,
+                    provisionalPromotionFingerprint: promotion.runtimeContractFingerprint,
+                    parallelProjectKey: projectKey,
+                });
+            }
+            return promotedLease;
+        }
+        catch {
+            await this.promotionStore.invalidate(active.repoId).catch(() => undefined);
+            active.lease = runtimeLease;
+            await this.writeLedger(runtimeLease);
+            return runtimeLease;
+        }
+    }
+    async launchNodeRuntime(dispatchAttemptId, fencingToken, portName, command, launcher, signal) {
+        const active = this.active.get(dispatchAttemptId);
+        if (!active || active.lease.fencingToken !== fencingToken || active.lease.state !== "active" || active.releasing) {
+            throw new Error("host_runtime_adapter_unavailable: an active matching host runtime lease is required.");
+        }
+        const portConfig = active.runtimeContract.contract.runtime.ports.find(port => port.name === portName);
+        if (!portConfig)
+            throw new Error(`host_runtime_adapter_invalid: configured port '${portName}' was not found.`);
+        if (active.lease.resources.ports.some(port => port.name === portName) || active.pendingAdapterLaunches.has(portName)) {
+            throw new Error(`host_runtime_adapter_conflict: configured port '${portName}' is already active.`);
+        }
+        const controller = linkedAbortController(signal);
+        let retainedByActiveRuntime = false;
+        const operation = (async () => {
+            const owner = hostPortOwner(active.lease);
+            const launched = await this.nodeAdapter.launch(owner, portConfig, command, launcher, controller.signal);
+            let cleaned = false;
+            const cleanup = async () => {
+                if (cleaned)
+                    return;
+                await launcher.stop(launched.value);
+                await this.portBroker.release(launched.reservation.reservationId, owner);
+                cleaned = true;
+                unlinkAbortController(controller, signal);
+            };
+            active.adapterCleanups.push(cleanup);
+            try {
+                if (active.releasing)
+                    throw new Error("host_runtime_adapter_cancelled: host runtime release started during launch.");
+                const runtimeLease = withRuntimeIsolationResources(active.lease, {
+                    ...active.lease.resources,
+                    ports: [...active.lease.resources.ports, {
+                            name: launched.reservation.name,
+                            protocol: launched.reservation.protocol,
+                            hostIp: launched.reservation.hostIp,
+                            hostPort: launched.reservation.hostPort,
+                            targetPort: launched.reservation.targetPort,
+                        }],
+                });
+                await this.writeLedger(runtimeLease);
+                active.lease = runtimeLease;
+                retainedByActiveRuntime = true;
+                return { ...launched, runtimeLease };
+            }
+            catch (error) {
+                try {
+                    await cleanup();
+                    removeCleanup(active.adapterCleanups, cleanup);
+                }
+                catch {
+                    // Preserve the cleanup and broker claim for the fenced release retry.
+                }
+                throw error;
+            }
+        })();
+        active.pendingAdapterLaunches.set(portName, { controller, promise: operation });
+        try {
+            return await operation;
+        }
+        finally {
+            active.pendingAdapterLaunches.delete(portName);
+            if (!retainedByActiveRuntime)
+                unlinkAbortController(controller, signal);
+        }
+    }
+    async release(dispatchAttemptId, fencingToken) {
+        const active = this.active.get(dispatchAttemptId);
+        this.pendingRenewals.delete(dispatchAttemptId);
+        if (!active) {
+            this.cancelAdmissionWaiters(dispatchAttemptId, fencingToken, "Managed host admission was released before acquisition.");
+            this.releaseSingletonKeys(dispatchAttemptId, fencingToken);
+            this.releaseParallelProjects(dispatchAttemptId, fencingToken);
+            this.deleteAdmission(dispatchAttemptId, fencingToken);
+            return null;
+        }
+        if (active.lease.fencingToken !== fencingToken)
+            return null;
+        active.releasing = true;
+        for (const pending of active.pendingAdapterLaunches.values()) {
+            pending.controller.abort("Host runtime release cancelled the pending adapter launch.");
+        }
+        await Promise.allSettled([...active.pendingAdapterLaunches.values()].map(pending => pending.promise));
+        let releasing = transitionRuntimeIsolationLease(active.lease, "releasing");
+        active.lease = releasing;
+        await this.writeLedger(releasing);
+        try {
+            await active.processSupervisor.stopAll(fencingToken, "Host runtime lease released.");
+            await releaseAdapterResources(active.adapterCleanups);
+            await fs.rm(active.attemptRoot, { recursive: true, force: true });
+            releasing = transitionRuntimeIsolationLease(releasing, "released");
+            active.lease = releasing;
+            await this.writeLedger(releasing);
+            await fs.rm(this.ledgerPath(dispatchAttemptId), { force: true });
+            this.active.delete(dispatchAttemptId);
+            this.processSupervisors.unregister(dispatchAttemptId, fencingToken);
+            this.releaseSingletonKeys(dispatchAttemptId, fencingToken);
+            this.releaseParallelProjects(dispatchAttemptId, fencingToken);
+            this.deleteAdmission(dispatchAttemptId, fencingToken);
+            return releasing;
+        }
+        catch (error) {
+            const degraded = transitionRuntimeIsolationLease(releasing, "degraded");
+            active.lease = degraded;
+            await this.writeLedger(degraded).catch(() => undefined);
+            throw new HostRuntimeLeaseCleanupError(degraded, error);
+        }
+    }
+    async readLedgers() {
+        const root = path.join(this.stateRoot, "runtime-ledger", "host");
+        const entries = await fs.readdir(root, { withFileTypes: true }).catch(error => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        const ledgers = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !/^[0-9a-f]{32}\.json$/u.test(entry.name))
+                continue;
+            try {
+                const value = JSON.parse(await fs.readFile(path.join(root, entry.name), "utf8"));
+                if (!validHostRuntimeLedger(value))
+                    continue;
+                const expectedName = `${uuidHex(value.runtimeLease.dispatchAttemptId, "dispatch attempt")}.json`;
+                if (entry.name !== expectedName)
+                    continue;
+                ledgers.push(value);
+            }
+            catch {
+                // An invalid ledger has no trustworthy ownership identity and is never reaped.
+            }
+        }
+        return ledgers;
+    }
+    async recoverPersistedProcesses(lease, attemptRoot) {
+        const logsRoot = path.join(attemptRoot, "logs");
+        const expectedAttemptRoot = path.resolve(this.attemptRoot(lease.dispatchAttemptId));
+        if (path.resolve(attemptRoot) !== expectedAttemptRoot) {
+            throw new Error("host_runtime_reaper_invalid: attempt path is outside the fenced attempt root.");
+        }
+        const entries = await fs.readdir(logsRoot, { withFileTypes: true }).catch(error => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        const outcomes = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !/^process-supervisor\.[a-z][a-z0-9_-]{0,31}\.\d+\.json$/u.test(entry.name))
+                continue;
+            const metadataPath = path.join(logsRoot, entry.name);
+            const value = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+            if (!validHostProcessSupervisorMetadata(value, lease)) {
+                throw new Error("host_runtime_reaper_invalid: process ownership metadata did not match the runtime lease.");
+            }
+            outcomes.push(await this.processRecovery.recover(value));
+        }
+        return outcomes;
+    }
+    async markLedgerDegraded(ledger) {
+        const lease = ledger.runtimeLease;
+        if (lease.state === "released")
+            return;
+        const degraded = transitionHostLeaseForCleanup(lease, "degraded");
+        const repoId = ledger.repoId ?? repoIdFromProjectSingletonKeys(lease.resources.singletonKeys);
+        this.rememberDegraded(degraded, repoId);
+        await this.writeLedger(degraded, repoId ?? undefined).catch(() => undefined);
+    }
+    rememberDegraded(lease, repoId) {
+        this.degraded.set(lease.dispatchAttemptId, { lease, repoId });
+        if (!repoId)
+            return;
+        const owner = { dispatchAttemptId: lease.dispatchAttemptId, fencingToken: lease.fencingToken };
+        const projectKey = projectHostRuntimeSingletonKey(repoId);
+        const existing = this.singletonOwners.get(projectKey);
+        if (!existing || sameSingletonOwner(existing, owner))
+            this.singletonOwners.set(projectKey, owner);
+    }
+    forgetDegraded(dispatchAttemptId, fencingToken) {
+        if (this.degraded.get(dispatchAttemptId)?.lease.fencingToken !== fencingToken)
+            return;
+        this.degraded.delete(dispatchAttemptId);
+        this.releaseSingletonKeys(dispatchAttemptId, fencingToken);
+        this.releaseParallelProjects(dispatchAttemptId, fencingToken);
+    }
+    attemptRoot(dispatchAttemptId) {
+        return path.join(this.stateRoot, "host-attempts", uuidHex(dispatchAttemptId, "dispatch attempt"));
+    }
+    async writeLedger(runtimeLease, explicitRepoId) {
+        const root = path.join(this.stateRoot, "runtime-ledger", "host");
+        await ensurePrivateDirectory(root);
+        const target = this.ledgerPath(runtimeLease.dispatchAttemptId);
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            const handle = await fs.open(temporary, "wx", 0o600);
+            try {
+                const repoId = explicitRepoId
+                    ?? this.active.get(runtimeLease.dispatchAttemptId)?.repoId
+                    ?? this.admissions.get(runtimeLease.dispatchAttemptId)?.repoId
+                    ?? this.degraded.get(runtimeLease.dispatchAttemptId)?.repoId
+                    ?? undefined;
+                const ledger = {
+                    schemaVersion: 1,
+                    ...(repoId ? { repoId } : {}),
+                    runtimeLease,
+                };
+                await handle.writeFile(`${JSON.stringify(ledger)}\n`);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await fs.rename(temporary, target);
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    ledgerPath(dispatchAttemptId) {
+        const attemptHex = uuidHex(dispatchAttemptId, "dispatch attempt");
+        return path.join(this.stateRoot, "runtime-ledger", "host", `${attemptHex}.json`);
+    }
+    singletonKeysAvailable(keys) {
+        return keys.every(key => !this.singletonOwners.has(key) && !this.parallelProjectOwners.has(key));
+    }
+    assignSingletonKeys(keys, owner) {
+        for (const key of keys)
+            this.singletonOwners.set(key, owner);
+    }
+    releaseSingletonKeys(dispatchAttemptId, fencingToken) {
+        for (const [key, owner] of this.singletonOwners) {
+            if (owner.dispatchAttemptId === dispatchAttemptId && owner.fencingToken === fencingToken) {
+                this.singletonOwners.delete(key);
+            }
+        }
+        this.drainAdmissionWaiters();
+    }
+    convertSingletonToParallelProject(key, owner) {
+        if (!sameSingletonOwner(this.singletonOwners.get(key), owner)) {
+            throw new Error("host_runtime_parallel_promotion_stale: matching exclusive project admission is required.");
+        }
+        this.assignParallelProject(key, owner);
+        this.singletonOwners.delete(key);
+        this.drainAdmissionWaiters();
+    }
+    parallelProjectOwned(key, owner) {
+        return sameSingletonOwner(this.parallelProjectOwners.get(key)?.get(owner.dispatchAttemptId), owner);
+    }
+    parallelProjectAvailable(key) {
+        return !this.singletonOwners.has(key)
+            && !this.singletonWaiters.some(waiter => waiter.keys.includes(key));
+    }
+    assignParallelProject(key, owner) {
+        const owners = this.parallelProjectOwners.get(key) ?? new Map();
+        owners.set(owner.dispatchAttemptId, owner);
+        this.parallelProjectOwners.set(key, owners);
+    }
+    releaseParallelProjectNoDrain(key, owner) {
+        const owners = this.parallelProjectOwners.get(key);
+        if (!sameSingletonOwner(owners?.get(owner.dispatchAttemptId), owner))
+            return;
+        owners.delete(owner.dispatchAttemptId);
+        if (owners.size === 0)
+            this.parallelProjectOwners.delete(key);
+    }
+    releaseParallelProjects(dispatchAttemptId, fencingToken) {
+        const owner = { dispatchAttemptId, fencingToken };
+        for (const key of [...this.parallelProjectOwners.keys()]) {
+            this.releaseParallelProjectNoDrain(key, owner);
+        }
+        this.drainAdmissionWaiters();
+    }
+    deleteAdmission(dispatchAttemptId, fencingToken) {
+        if (this.admissions.get(dispatchAttemptId)?.fencingToken === fencingToken) {
+            this.admissions.delete(dispatchAttemptId);
+        }
+    }
+    renewAdmissionWaiterDeadline(dispatchAttemptId, fencingToken, expiresAt) {
+        for (const waiter of [...this.singletonWaiters, ...this.parallelProjectWaiters]) {
+            if (!sameSingletonOwner(waiter.owner, { dispatchAttemptId, fencingToken })
+                || Date.parse(expiresAt) <= Date.parse(waiter.expiresAt))
+                continue;
+            waiter.expiresAt = expiresAt;
+            clearAdmissionDeadline(waiter);
+            waiter.deadlineTimer = scheduleAdmissionDeadline(waiter.expiresAt, waiter.expire);
+        }
+    }
+    clearPendingRenewal(owner) {
+        if (this.pendingRenewals.get(owner.dispatchAttemptId)?.fencingToken === owner.fencingToken) {
+            this.pendingRenewals.delete(owner.dispatchAttemptId);
+        }
+    }
+    cancelAdmissionWaiters(dispatchAttemptId, fencingToken, reason) {
+        const owner = { dispatchAttemptId, fencingToken };
+        for (const waiters of [this.singletonWaiters, this.parallelProjectWaiters]) {
+            for (let index = waiters.length - 1; index >= 0; index -= 1) {
+                const waiter = waiters[index];
+                if (!sameSingletonOwner(waiter.owner, owner))
+                    continue;
+                waiters.splice(index, 1);
+                clearAdmissionDeadline(waiter);
+                waiter.signal?.removeEventListener("abort", waiter.abort);
+                waiter.reject(new Error(`host_runtime_admission_cancelled: ${reason}`));
+            }
+        }
+        this.drainAdmissionWaiters();
+    }
+    drainSingletonWaiters() {
+        for (let index = 0; index < this.singletonWaiters.length;) {
+            const waiter = this.singletonWaiters[index];
+            if (waiter.signal?.aborted) {
+                this.singletonWaiters.splice(index, 1);
+                clearAdmissionDeadline(waiter);
+                waiter.signal.removeEventListener("abort", waiter.abort);
+                this.clearPendingRenewal(waiter.owner);
+                waiter.reject(cancellationError(waiter.signal));
+                continue;
+            }
+            if (admissionExpired(waiter.expiresAt)) {
+                this.singletonWaiters.splice(index, 1);
+                clearAdmissionDeadline(waiter);
+                waiter.signal?.removeEventListener("abort", waiter.abort);
+                this.clearPendingRenewal(waiter.owner);
+                waiter.reject(new HostRuntimeAdmissionExpiredError());
+                continue;
+            }
+            if (!this.singletonKeysAvailable(waiter.keys)) {
+                index += 1;
+                continue;
+            }
+            this.singletonWaiters.splice(index, 1);
+            clearAdmissionDeadline(waiter);
+            waiter.signal?.removeEventListener("abort", waiter.abort);
+            this.assignSingletonKeys(waiter.keys, waiter.owner);
+            waiter.resolve(waiter.keys);
+        }
+    }
+    drainParallelProjectWaiters() {
+        for (let index = 0; index < this.parallelProjectWaiters.length;) {
+            const waiter = this.parallelProjectWaiters[index];
+            if (waiter.signal?.aborted) {
+                this.parallelProjectWaiters.splice(index, 1);
+                clearAdmissionDeadline(waiter);
+                waiter.signal.removeEventListener("abort", waiter.abort);
+                this.clearPendingRenewal(waiter.owner);
+                waiter.reject(cancellationError(waiter.signal));
+                continue;
+            }
+            if (admissionExpired(waiter.expiresAt)) {
+                this.parallelProjectWaiters.splice(index, 1);
+                clearAdmissionDeadline(waiter);
+                waiter.signal?.removeEventListener("abort", waiter.abort);
+                this.clearPendingRenewal(waiter.owner);
+                waiter.reject(new HostRuntimeAdmissionExpiredError());
+                continue;
+            }
+            if (!this.parallelProjectAvailable(waiter.key)) {
+                index += 1;
+                continue;
+            }
+            this.parallelProjectWaiters.splice(index, 1);
+            clearAdmissionDeadline(waiter);
+            waiter.signal?.removeEventListener("abort", waiter.abort);
+            this.assignParallelProject(waiter.key, waiter.owner);
+            waiter.resolve();
+        }
+    }
+    drainAdmissionWaiters() {
+        this.drainSingletonWaiters();
+        this.drainParallelProjectWaiters();
+    }
+}
+export class HostRuntimeLeaseCleanupError extends Error {
+    lease;
+    constructor(lease, cause) {
+        super(`host_runtime_cleanup_degraded: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.lease = lease;
+        this.name = "HostRuntimeLeaseCleanupError";
+    }
+}
+export class HostRuntimeAdmissionExpiredError extends Error {
+    constructor() {
+        super("host_runtime_admission_expired: dispatch lease expired while waiting for managed host admission.");
+        this.name = "HostRuntimeAdmissionExpiredError";
+    }
+}
+export function hostRuntimeEventResources(lease, runtimeContract) {
+    const requestedHostConcurrency = runtimeContract?.contract.runtime.hostConcurrency ?? "serial";
+    const configuredLaunches = runtimeContract?.contract.runtime.ports.filter(port => port.launch !== null) ?? [];
+    const verifiedLaunches = configuredLaunches.filter(configured => lease.resources.ports.some(port => port.name === configured.name));
+    const effectiveConcurrency = effectiveHostConcurrency(lease, runtimeContract);
+    return {
+        agentContainer: null,
+        sidecarContainers: [],
+        networks: [],
+        volumes: [],
+        publishedPorts: lease.resources.ports,
+        hostConcurrency: effectiveConcurrency,
+        requestedHostConcurrency,
+        hostParallelPromotion: effectiveConcurrency === "host_parallel_safe"
+            ? "observed_probe_passed"
+            : requestedHostConcurrency !== "parallel"
+                ? "not_requested"
+                : configuredLaunches.length > 0 && verifiedLaunches.length === configuredLaunches.length
+                    ? "pending_live_parallel_proof"
+                    : "pending_adapter_probe",
+        verifiedRuntimePorts: verifiedLaunches.map(port => port.name),
+        runtimeContractSource: runtimeContract?.source ?? "default",
+        requestedPorts: runtimeContract?.contract.runtime.ports.map(port => port.name) ?? [],
+        singletonKeys: lease.resources.singletonKeys,
+        processSupervisorId: lease.resources.processSupervisorId,
+        runtimeLease: lease,
+    };
+}
+export function hostRuntimeSingletonKeys(dispatch) {
+    return [projectHostRuntimeSingletonKey(dispatch.repo.id)];
+}
+function hostRuntimeEnvironment(sessionId, lease, runtimeContract) {
+    const pathFor = (role) => lease.resources.paths.find(entry => entry.role === role)?.path ?? "";
+    const environment = {
+        FORGE_SESSION_ID: sessionId,
+        FORGE_RUNTIME_MODE: "host",
+        FORGE_RESOURCE_LEASE_ID: lease.leaseId,
+        FORGE_DISPATCH_ATTEMPT_ID: lease.dispatchAttemptId,
+        FORGE_EXECUTION_LEASE_ID: lease.executionLeaseId,
+        FORGE_FENCING_TOKEN: lease.fencingToken,
+        FORGE_WORKSPACE: lease.worktreePath,
+        FORGE_WORKTREE_PATH: lease.worktreePath,
+        FORGE_TMPDIR: pathFor("temporary"),
+        FORGE_LOG_DIR: pathFor("logs"),
+        FORGE_CACHE_DIR: pathFor("cache"),
+        FORGE_BROWSER_PROFILE_DIR: pathFor("browser_profile"),
+        FORGE_TEST_OUTPUT_DIR: pathFor("test_output"),
+        FORGE_PROCESS_SUPERVISOR_ID: lease.resources.processSupervisorId ?? "",
+        FORGE_PROCESS_SUPERVISOR_METADATA_PATH: pathFor("process_supervisor_metadata"),
+        FORGE_HOST_CONCURRENCY: effectiveHostConcurrency(lease, runtimeContract),
+        FORGE_HOST_CONCURRENCY_REQUESTED: runtimeContract.contract.runtime.hostConcurrency,
+        FORGE_HOST_RUNTIME_CONTRACT_SOURCE: runtimeContract.source,
+        FORGE_SINGLETON_KEYS: lease.resources.singletonKeys.join(","),
+        TMPDIR: pathFor("temporary"),
+        TMP: pathFor("temporary"),
+        TEMP: pathFor("temporary"),
+        XDG_CACHE_HOME: pathFor("cache"),
+        NPM_CONFIG_CACHE: path.join(pathFor("cache"), "npm"),
+    };
+    if (lease.resources.singletonKeys.length === 0)
+        delete environment.FORGE_SINGLETON_KEYS;
+    const resolvedBaseUrls = [];
+    for (const assigned of lease.resources.ports) {
+        const configured = runtimeContract.contract.runtime.ports.find(port => port.name === assigned.name);
+        if (!configured || assigned.hostIp !== "127.0.0.1")
+            continue;
+        Object.assign(environment, hostPortEnvironment(configured, assigned.hostIp, assigned.hostPort));
+        const normalizedName = assigned.name.toUpperCase().replaceAll(/[^A-Z0-9]/gu, "_");
+        environment[`FORGE_${normalizedName}_PORT`] = String(assigned.hostPort);
+        if (configured.baseUrlEnv && configured.format) {
+            const baseUrl = hostPortEnvironment(configured, assigned.hostIp, assigned.hostPort)[configured.baseUrlEnv];
+            if (baseUrl) {
+                environment[`FORGE_${normalizedName}_URL`] = baseUrl;
+                resolvedBaseUrls.push(baseUrl);
+            }
+        }
+    }
+    if (resolvedBaseUrls.length === 1)
+        environment.FORGE_BASE_URL = resolvedBaseUrls[0];
+    return environment;
+}
+function effectiveHostConcurrency(lease, runtimeContract) {
+    if (!runtimeContract || !hostRuntimeParallelEligible(runtimeContract))
+        return "host_serial_only";
+    const requiredPorts = configuredLaunchPortNames(runtimeContract);
+    const everyPortVerified = requiredPorts.length > 0
+        && requiredPorts.every(name => lease.resources.ports.some(port => port.name === name));
+    const projectSingletonHeld = lease.resources.singletonKeys.some(key => key.endsWith(":host-runtime"));
+    return everyPortVerified && !projectSingletonHeld ? "host_parallel_safe" : "host_serial_only";
+}
+function projectHostRuntimeSingletonKey(repoId) {
+    return `project:${repoId.toLowerCase()}:host-runtime`;
+}
+function capacityProject(projects, repoId) {
+    const normalized = repoId.trim().toLowerCase();
+    const existing = projects.get(normalized);
+    if (existing)
+        return existing;
+    const created = {
+        repoId: normalized,
+        safetyClass: null,
+        activeAttempts: 0,
+        reservedAttempts: 0,
+        waitingAttempts: 0,
+        degradedAttempts: 0,
+    };
+    projects.set(normalized, created);
+    return created;
+}
+function conservativeSafetyClass(left, right) {
+    if (!left)
+        return right;
+    const rank = {
+        host_serial_only: 0,
+        host_parallel_candidate: 1,
+        host_parallel_safe: 2,
+    };
+    return rank[right] < rank[left] ? right : left;
+}
+function repoIdFromProjectSingletonKeys(keys) {
+    return keys.map(repoIdFromProjectSingletonKey).find((value) => value !== null) ?? null;
+}
+function repoIdFromProjectSingletonKey(key) {
+    const prefix = "project:";
+    const suffix = ":host-runtime";
+    return key.startsWith(prefix) && key.endsWith(suffix)
+        ? key.slice(prefix.length, -suffix.length)
+        : null;
+}
+function sameSingletonOwner(left, right) {
+    return left?.dispatchAttemptId === right.dispatchAttemptId && left.fencingToken === right.fencingToken;
+}
+function hostPortOwner(lease) {
+    const processSupervisorId = lease.resources.processSupervisorId;
+    if (!processSupervisorId) {
+        throw new Error("host_runtime_adapter_invalid: process supervisor identity is required.");
+    }
+    return {
+        dispatchAttemptId: lease.dispatchAttemptId,
+        executionLeaseId: lease.executionLeaseId,
+        fencingToken: lease.fencingToken,
+        processSupervisorId,
+    };
+}
+function linkedAbortController(signal) {
+    const controller = new AbortController();
+    if (signal?.aborted) {
+        controller.abort(signal.reason);
+    }
+    else {
+        signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true, signal: controller.signal });
+    }
+    return controller;
+}
+function unlinkAbortController(controller, _signal) {
+    if (!controller.signal.aborted)
+        controller.abort("Host adapter launch settled.");
+}
+function removeCleanup(cleanups, cleanup) {
+    const index = cleanups.indexOf(cleanup);
+    if (index >= 0)
+        cleanups.splice(index, 1);
+}
+async function releaseAdapterResources(cleanups) {
+    const pending = cleanups.splice(0);
+    const failed = [];
+    let firstError;
+    for (const cleanup of pending.reverse()) {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            firstError ??= error;
+            failed.unshift(cleanup);
+        }
+    }
+    cleanups.push(...failed);
+    if (firstError !== undefined)
+        throw firstError;
+}
+function cancellationError(signal) {
+    return new Error(String(signal?.reason ?? "Dispatch cancelled while waiting for host runtime singleton ownership."));
+}
+function validHostRuntimeLedger(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const ledger = value;
+    return ledger.schemaVersion === 1
+        && (ledger.repoId === undefined || /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu.test(ledger.repoId))
+        && validRuntimeIsolationLease(ledger.runtimeLease)
+        && ledger.runtimeLease.mode === "host";
+}
+function validHostProcessSupervisorMetadata(value, lease) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const metadata = value;
+    return metadata.schemaVersion === 1
+        && /^host-[0-9a-f]{32}$/u.test(metadata.supervisorId)
+        && (metadata.strategy === "windows_job_object" || metadata.strategy === "unix_process_group")
+        && Number.isSafeInteger(metadata.rootPid)
+        && metadata.rootPid > 0
+        && Number.isFinite(Date.parse(metadata.rootCreatedAt))
+        && (metadata.rootIdentity == null
+            || (typeof metadata.rootIdentity === "string" && metadata.rootIdentity.length <= 256))
+        && /^[0-9a-f]{64}$/u.test(metadata.commandDigest)
+        && path.resolve(metadata.worktreePath) === path.resolve(lease.worktreePath)
+        && metadata.runtimeLeaseId === lease.executionLeaseId
+        && metadata.dispatchAttemptId === lease.dispatchAttemptId
+        && metadata.fencingToken === lease.fencingToken
+        && Number.isSafeInteger(metadata.bridgePid)
+        && metadata.bridgePid > 0;
+}
+function transitionHostLeaseForCleanup(lease, state) {
+    if (lease.state === state || lease.state === "released")
+        return lease;
+    return transitionRuntimeIsolationLease(lease, state);
+}
+function throwIfAdmissionExpired(expiresAt) {
+    if (admissionExpired(expiresAt))
+        throw new HostRuntimeAdmissionExpiredError();
+}
+function admissionExpired(expiresAt) {
+    const deadline = Date.parse(expiresAt);
+    return !Number.isFinite(deadline) || deadline <= Date.now();
+}
+function scheduleAdmissionDeadline(expiresAt, expire) {
+    const delay = Math.max(0, Date.parse(expiresAt) - Date.now());
+    const timer = setTimeout(expire, Math.min(delay, 2_147_483_647));
+    timer.unref?.();
+    return timer;
+}
+function clearAdmissionDeadline(waiter) {
+    if (waiter.deadlineTimer)
+        clearTimeout(waiter.deadlineTimer);
+    waiter.deadlineTimer = null;
+}
+async function ensurePrivateDirectory(directory) {
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await fs.chmod(directory, 0o700);
+}
+async function containedWorkingDirectory(worktreePath, configuredDirectory) {
+    const [realWorktree, realDirectory] = await Promise.all([
+        fs.realpath(worktreePath),
+        fs.realpath(path.resolve(worktreePath, configuredDirectory)),
+    ]);
+    const relative = path.relative(realWorktree, realDirectory);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("host_runtime_project_invalid: launch working directory must remain inside the prepared worktree.");
+    }
+    return realDirectory;
+}
+function uuidHex(value, label) {
+    const normalized = value.replaceAll("-", "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/u.test(normalized)) {
+        throw new Error(`host_runtime_lease_invalid: ${label} id must be a full UUID.`);
+    }
+    return normalized;
+}