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

package/dist/session/session.service.js

@@ -1,12 +1,123 @@
-import { redactSecrets } from "../shared/redaction/redaction.js";
+import { redactRunnerDispatchEvent, redactRunOnceResultPacket } from "./session-redaction.js";
 import { RoutingProviderCliService } from "./provider-cli/provider-cli.service.js";
 import { GitWorktreeService } from "../worktree/worktree.service.js";
+import { SandboxWorkspaceService } from "../sandbox/workspace.service.js";
+import { HostRuntimeAdmissionExpiredError, hostRuntimeEventResources, } from "../runtime/host-runtime-lease.js";
+import { configuredLaunchPortNames, hostRuntimeContractFingerprint, hostRuntimeParallelEligible, } from "../runtime/host-runtime-promotion.js";
+const minimumReadinessProbeStartupBudgetMs = 150_000;
 export class BridgeSessionService {
     worktrees;
     providerCli;
-    constructor(worktrees = new GitWorktreeService(), providerCli = new RoutingProviderCliService()) {
+    hostRuntime;
+    constructor(worktrees = process.env.FORGE_SANDBOX_ID
+        ? new SandboxWorkspaceService()
+        : new GitWorktreeService(), providerCli = new RoutingProviderCliService(), hostRuntime) {
         this.worktrees = worktrees;
         this.providerCli = providerCli;
+        this.hostRuntime = hostRuntime;
+    }
+    async updateLease(dispatchAttemptId, fencingToken, expiresAt) {
+        await this.hostRuntime?.updateLease(dispatchAttemptId, fencingToken, expiresAt);
+    }
+    async reapHostRuntime(options) {
+        return await this.hostRuntime?.reap?.(options) ?? null;
+    }
+    runtimeCapacity() {
+        return this.hostRuntime?.snapshot?.() ?? null;
+    }
+    async probeHostRuntime(request, signal) {
+        if (!this.hostRuntime) {
+            return failedProbe("host_runtime_unavailable", "This bridge does not provide managed host runtime isolation.");
+        }
+        const dispatch = readinessProbeDispatch(request);
+        let worktree = null;
+        let admissionAcquired = false;
+        let runtimeStarted = false;
+        let result;
+        let cleanupFailure = null;
+        try {
+            throwIfAborted(signal);
+            await this.hostRuntime.invalidatePromotion?.(request.repoId);
+            await this.hostRuntime.acquire(dispatch, signal);
+            admissionAcquired = true;
+            assertReadinessProbeStartupBudget(request.expiresAt);
+            worktree = await this.worktrees.prepare({
+                repo: dispatch.repo,
+                workItem: dispatch.workItem,
+                baseBranch: request.revision,
+                worktreeKey: dispatch.lease.worktreeKey,
+                ownerType: "project",
+                ownerId: request.projectId,
+                lane: "runtime_readiness",
+                phase: "readiness_probe",
+                allowedRepoRoot: request.repoRoot,
+                // Readiness probes are disposable infrastructure checks, not agent lanes.
+                // Always remove their worktree even when the bridge is configured to retain
+                // failed agent worktrees for inspection.
+                cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
+                artifacts: [],
+            });
+            assertReadinessProbeStartupBudget(request.expiresAt);
+            let started = await this.hostRuntime.start(dispatch, worktree.worktreePath, signal);
+            runtimeStarted = true;
+            const discovery = started.runtimeContract.discovery;
+            if (!hostRuntimeParallelEligible(started.runtimeContract)) {
+                result = {
+                    status: "serialized",
+                    runtimeContractFingerprint: hostRuntimeContractFingerprint(started.runtimeContract),
+                    runtimeContractSource: started.runtimeContract.source,
+                    reasonCode: discovery?.reasonCode ?? "host_runtime_contract_serialized",
+                    reasonMessage: discovery?.summary ?? "The detected runtime requires serialized host execution.",
+                    checkedAt: new Date().toISOString(),
+                };
+            }
+            else {
+                assertReadinessProbeStartupBudget(request.expiresAt);
+                started = await this.hostRuntime.startConfiguredProject(request.requestId, request.fencingToken, signal);
+                const requiredPorts = configuredLaunchPortNames(started.runtimeContract);
+                const verifiedPorts = started.lease.resources.ports.map(port => port.name);
+                const verified = requiredPorts.length > 0 && requiredPorts.every(name => verifiedPorts.includes(name));
+                result = verified
+                    ? {
+                        status: "parallel_ready",
+                        runtimeContractFingerprint: hostRuntimeContractFingerprint(started.runtimeContract),
+                        runtimeContractSource: started.runtimeContract.source,
+                        reasonCode: null,
+                        reasonMessage: null,
+                        qaAppLaunchTarget: managedQaLaunchTarget(started.runtimeContract),
+                        checkedAt: new Date().toISOString(),
+                    }
+                    : failedProbe("host_runtime_probe_unverified", "The application did not prove ownership and readiness on every Forge-assigned port.");
+            }
+        }
+        catch (error) {
+            result = failedProbe(probeFailureCode(error), probeFailureMessage(error));
+        }
+        finally {
+            if (runtimeStarted || admissionAcquired) {
+                try {
+                    const released = await this.hostRuntime.release(request.requestId, request.fencingToken);
+                    if (runtimeStarted && !released)
+                        cleanupFailure = new Error("The runtime lease was no longer current during cleanup.");
+                }
+                catch (error) {
+                    cleanupFailure = error instanceof Error ? error : new Error(String(error));
+                }
+            }
+            if (worktree) {
+                try {
+                    await this.worktrees.release(worktree);
+                }
+                catch (error) {
+                    cleanupFailure ??= error instanceof Error ? error : new Error(String(error));
+                }
+            }
+        }
+        if (cleanupFailure) {
+            await this.hostRuntime.invalidatePromotion?.(request.repoId).catch(() => undefined);
+            return failedProbe("host_runtime_cleanup_degraded", `Forge could not prove exact readiness cleanup: ${cleanupFailure.message}`);
+        }
+        return result;
     }
     async runOnce(dispatch, sink, signal) {
         validateApiKeySecretGrant(dispatch);
@@ -16,7 +127,14 @@ export class BridgeSessionService {
             if (signal?.aborted) {
                 return;
             }
-            const redacted = redactSecrets(event, redactionSecrets);
+            const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
+            if (redacted.eventType !== "provider_tool_heartbeat") {
+                events.push(redacted);
+            }
+            await sink.emit(redacted);
+        };
+        const emitLifecycle = async (event) => {
+            const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
             events.push(redacted);
             await sink.emit(redacted);
         };
@@ -27,72 +145,195 @@ export class BridgeSessionService {
             content: "forge-bridge accepted run-once dispatch.",
             eventType: "dispatch_accepted"
         });
-        if (dispatch.draft) {
-            const run = await this.providerCli.runDraft({
-                dispatch,
-                emit,
-                signal
-            });
-            throwIfAborted(signal);
-            return redactSecrets({
-                schemaVersion: 1,
-                exitCode: 0,
-                summary: run.summary,
-                events,
-                spec: run.spec ?? null,
-                artifact: run.artifact ?? null,
-                artifacts: run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : []
-            }, redactionSecrets);
-        }
-        const worktree = await this.worktrees.prepare({
-            repo: dispatch.repo,
-            workItem: dispatch.workItem,
-            baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
-            worktreeKey: dispatch.lease.worktreeKey,
-            ownerType: dispatch.cycleRun.ownerType ?? dispatch.lease.ownerType ?? null,
-            ownerId: dispatch.cycleRun.ownerId ?? dispatch.lease.ownerId ?? null,
-            lane: dispatch.execution.lane,
-            phase: dispatch.cycleRun.phase,
-            allowedRepoRoot: dispatch.serverLocal.repoRoot,
-            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
-            artifacts: dispatch.artifacts,
-            qaRework: dispatch.qaRework,
-            warmPathOverrides: dispatch.warmPathOverrides
-        });
-        const providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
-        throwIfAborted(signal);
-        await emit({
-            role: "runner",
-            kind: "checkpoint",
-            content: `Prepared worktree ${worktree.branchName}.`,
-            eventType: "worktree_prepared"
-        });
-        if (worktree.dependencyWarm) {
-            await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
-        }
+        let worktree = null;
+        let hostSingletonKeys = null;
+        let hostLease = null;
         try {
+            if (dispatch.sandbox?.executionMode === "host" && this.hostRuntime) {
+                const capacity = this.hostRuntime.snapshot?.() ?? null;
+                const projectCapacity = capacity?.projects.find(project => project.repoId === dispatch.repo.id) ?? null;
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: capacity
+                        ? `Waiting for runner capacity before preparing the worktree (queue position ${capacity.waitingAttempts + 1}; runner ${capacity.activeAttempts} active, ${capacity.reservedAttempts} reserved; project ${projectCapacity?.activeAttempts ?? 0} active, ${projectCapacity?.waitingAttempts ?? 0} already waiting). Forge will continue automatically when admission is available.`
+                        : "Waiting for runner capacity before preparing the worktree. Forge will continue automatically when admission is available.",
+                    eventType: "host_runtime_admission_waiting",
+                    data: capacity ? JSON.stringify({
+                        queue_position: capacity.waitingAttempts + 1,
+                        runner_active_attempts: capacity.activeAttempts,
+                        runner_reserved_attempts: capacity.reservedAttempts,
+                        runner_waiting_attempts: capacity.waitingAttempts,
+                        project_active_attempts: projectCapacity?.activeAttempts ?? 0,
+                        project_reserved_attempts: projectCapacity?.reservedAttempts ?? 0,
+                        project_waiting_attempts: projectCapacity?.waitingAttempts ?? 0,
+                        project_safety_class: projectCapacity?.safetyClass ?? "unknown",
+                    }) : undefined,
+                });
+                try {
+                    hostSingletonKeys = await this.hostRuntime.acquire(dispatch, signal);
+                }
+                catch (error) {
+                    if (error instanceof HostRuntimeAdmissionExpiredError) {
+                        await emitLifecycle({
+                            role: "runner",
+                            kind: "error",
+                            content: "Managed host admission expired while the project singleton remained busy; no worktree or runtime resources were created.",
+                            eventType: "host_runtime_admission_expired",
+                        }).catch(() => undefined);
+                    }
+                    throw error;
+                }
+                throwIfAborted(signal);
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: hostSingletonKeys.length > 0
+                        ? `Acquired managed host singleton ${hostSingletonKeys.join(", ")}.`
+                        : "Observed assigned-port evidence permits provisional parallel host admission; the prepared runtime contract must still match before launch.",
+                    eventType: "host_runtime_admission_acquired",
+                });
+            }
+            try {
+                worktree = await this.worktrees.prepare({
+                    repo: dispatch.repo,
+                    workItem: dispatch.workItem,
+                    baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
+                    worktreeKey: dispatch.lease.worktreeKey,
+                    ownerType: dispatch.cycleRun.ownerType ?? dispatch.lease.ownerType ?? null,
+                    ownerId: dispatch.cycleRun.ownerId ?? dispatch.lease.ownerId ?? null,
+                    lane: dispatch.execution.lane,
+                    phase: dispatch.cycleRun.phase,
+                    allowedRepoRoot: dispatch.serverLocal.repoRoot,
+                    cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
+                    artifacts: dispatch.artifacts,
+                    priorPhaseArtifacts: dispatch.priorPhaseArtifacts,
+                    qaRework: dispatch.qaRework,
+                    warmPathOverrides: dispatch.warmPathOverrides
+                });
+            }
+            catch (error) {
+                throw new Error(`worktree_prepare_failed: ${failureMessage(error)}`, { cause: error });
+            }
+            let providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
             throwIfAborted(signal);
-            const lane = dispatch.execution.lane.toLowerCase();
-            const role = dispatch.execution.role.toLowerCase();
+            await emit({
+                role: "runner",
+                kind: "checkpoint",
+                content: `Prepared worktree ${worktree.branchName}.`,
+                eventType: "worktree_prepared"
+            });
+            if ((worktree.hydratedPriorPhaseArtifactCount ?? 0) > 0) {
+                await emit({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Hydrated ${worktree.hydratedPriorPhaseArtifactCount} persisted prior-phase artifact(s) into the prepared worktree.`,
+                    eventType: "prior_phase_artifacts_hydrated"
+                });
+            }
+            if (worktree.dependencyWarm) {
+                await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
+            }
+            if (dispatch.sandbox?.executionMode === "host" && this.hostRuntime) {
+                hostLease = await this.hostRuntime.start(dispatch, worktree.worktreePath, signal);
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Host runtime lease ${hostLease.lease.leaseId} is active for this worktree.`,
+                    eventType: "sandbox_started",
+                    occurredAt: hostLease.lease.stateChangedAt,
+                    data: JSON.stringify(hostRuntimeEventResources(hostLease.lease, hostLease.runtimeContract, hostLease.executionClass)),
+                });
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Managed host fallback isolates the worktree, attempt paths, assigned loopback ports, and supervised process trees, but not the host filesystem, network, credentials, or kernel. Serialized projects also hold a runner-local singleton. Enable Run in Docker in Project Settings when stronger isolation is required.",
+                    eventType: "host_runtime_isolation_notice",
+                    data: JSON.stringify({
+                        isolationStrength: "managed_host_process",
+                        remediation: "Enable Run in Docker in Project Settings.",
+                    }),
+                });
+                const unconfiguredPortCount = hostLease.lease.resources.ports.length;
+                hostLease = await this.hostRuntime.startConfiguredProject(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken, signal);
+                if (hostLease.lease.resources.ports.length > unconfiguredPortCount) {
+                    const assigned = hostLease.lease.resources.ports.at(-1);
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Verified supervised project runtime ${assigned.name} on ${assigned.hostIp}:${assigned.hostPort}.`,
+                        eventType: "host_runtime_project_ready",
+                        data: JSON.stringify(hostRuntimeEventResources(hostLease.lease, hostLease.runtimeContract, hostLease.executionClass)),
+                    });
+                }
+            }
+            providerDispatch = withMaterializedManagedQaTarget(providerDispatch, hostLease);
+            if (dispatch.draft) {
+                throwIfAborted(signal);
+                const processRunner = hostLease && dispatch.sandbox
+                    ? this.hostRuntime?.providerProcessRunner?.(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken) ?? undefined
+                    : undefined;
+                const run = await this.providerCli.runDraft({
+                    dispatch: providerDispatch,
+                    worktree,
+                    runtimeEnvironment: hostLease?.environment,
+                    processRunner,
+                    emit,
+                    signal
+                });
+                throwIfAborted(signal);
+                const draftArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
+                return redactRunOnceResultPacket({
+                    schemaVersion: 1,
+                    exitCode: 0,
+                    summary: run.summary,
+                    events,
+                    spec: run.spec ?? null,
+                    artifact: run.artifact ?? null,
+                    artifacts: draftArtifacts
+                }, redactionSecrets);
+            }
+            throwIfAborted(signal);
+            const lane = dispatch.execution.lane.trim().toLowerCase();
+            const role = dispatch.execution.role.trim().toLowerCase();
+            const cycleKind = dispatch.cycleRun.kind.trim().toLowerCase();
             const isQa = role === "qa" || lane === "qa";
-            const isArchitect = role === "architect" || lane === "architect" || dispatch.cycleRun.kind.toLowerCase() === "architect";
+            const isArchitect = role === "architect" || lane === "architect" || cycleKind === "architect";
+            const isCiRepair = role === "ci_repair" || lane === "ci_repair" || cycleKind === "pr_checks";
             const isConflictResolve = role === "conflict_resolve" || lane === "conflict_resolve";
             const context = {
                 dispatch: providerDispatch,
                 worktree,
+                runtimeEnvironment: hostLease?.environment,
+                processRunner: hostLease && dispatch.sandbox
+                    ? this.hostRuntime?.providerProcessRunner?.(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken) ?? undefined
+                    : undefined,
                 emit,
                 signal
             };
-            const run = isQa
-                ? await this.providerCli.runQa(context)
-                : isArchitect
-                    ? await this.providerCli.runArchitect(context)
-                    : isConflictResolve
-                        ? await this.providerCli.runConflictResolve(context)
-                        : await this.providerCli.runImplementation(context);
+            let run;
+            try {
+                run = isQa
+                    ? await this.providerCli.runQa(context)
+                    : isArchitect
+                        ? await this.providerCli.runArchitect(context)
+                        : isCiRepair
+                            ? await this.providerCli.runCiRepair(context)
+                            : isConflictResolve
+                                ? await this.providerCli.runConflictResolve(context)
+                                : await this.providerCli.runImplementation(context);
+            }
+            catch (error) {
+                const message = failureMessage(error);
+                if (message.includes("attempt_process_supervisor_start_")
+                    || message.includes("host_process_supervisor_start_")) {
+                    throw new Error(`provider_start_unavailable: ${message}`, { cause: error });
+                }
+                throw error;
+            }
             throwIfAborted(signal);
             const phaseArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
-            return redactSecrets({
+            return redactRunOnceResultPacket({
                 schemaVersion: 1,
                 exitCode: 0,
                 summary: run.summary,
@@ -103,10 +344,191 @@ export class BridgeSessionService {
             }, redactionSecrets);
         }
         finally {
-            await this.worktrees.release(worktree);
+            if (hostLease && dispatch.sandbox) {
+                const teardownAt = new Date().toISOString();
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Releasing host runtime lease ${hostLease.lease.leaseId}.`,
+                    eventType: "sandbox_teardown_started",
+                    occurredAt: teardownAt,
+                }).catch(() => undefined);
+                try {
+                    const released = await this.hostRuntime?.release(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+                    if (!released) {
+                        await emitLifecycle({
+                            role: "runner",
+                            kind: "error",
+                            content: "Host runtime cleanup requires reconciliation: the runtime lease was not current during release.",
+                            eventType: "teardown_failed",
+                            occurredAt: new Date().toISOString(),
+                        }).catch(() => undefined);
+                    }
+                    else {
+                        await emitLifecycle({
+                            role: "runner",
+                            kind: "checkpoint",
+                            content: `Released host runtime lease ${released.leaseId}.`,
+                            eventType: "sandbox_teardown_completed",
+                            occurredAt: released.releasedAt,
+                        }).catch(() => undefined);
+                    }
+                }
+                catch (error) {
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "error",
+                        content: `Host runtime cleanup requires reconciliation: ${error instanceof Error ? error.message : String(error)}`,
+                        eventType: "teardown_failed",
+                        occurredAt: new Date().toISOString(),
+                    }).catch(() => undefined);
+                }
+            }
+            if (!hostLease && hostSingletonKeys && dispatch.sandbox) {
+                await this.hostRuntime?.release(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken).catch(() => undefined);
+            }
+            if (worktree)
+                await this.worktrees.release(worktree);
         }
     }
 }
+function failureMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function readinessProbeDispatch(request) {
+    return {
+        schemaVersion: 2,
+        userId: request.userId,
+        workItem: {
+            id: request.projectId,
+            kind: "runtime_readiness",
+            title: "Automatic host-isolation readiness check",
+            description: "Internal readiness proof without a provider agent.",
+            acceptanceCriteria: "",
+            reproSteps: "",
+            systemInfo: "",
+        },
+        repo: {
+            id: request.repoId,
+            name: request.repoName,
+            remoteUrl: request.remoteUrl,
+            defaultBranch: request.defaultBranch,
+            cloneOnDemand: request.cloneOnDemand,
+            serverLocalPath: request.runnerRepoLocalPath,
+        },
+        cycleRun: {
+            id: request.requestId,
+            ownerType: "project",
+            ownerId: request.projectId,
+            kind: "runtime_readiness",
+            phase: "readiness_probe",
+            requestedBase: request.revision,
+            baseBranch: request.revision,
+            attempt: request.attempt,
+            model: "none",
+        },
+        session: { id: request.requestId, model: "none", lane: "runtime_readiness" },
+        lease: {
+            id: request.requestId,
+            ownerType: "project",
+            ownerId: request.projectId,
+            worktreeKey: `runtime-readiness-${request.requestId}`,
+            lane: "runtime_readiness",
+            fencingToken: request.fencingToken,
+            expiresAt: request.expiresAt,
+        },
+        execution: {
+            provider: "none",
+            model: "none",
+            authKind: "none",
+            location: "bridge",
+            runnerId: request.runnerId,
+            repoId: request.repoId,
+            role: "runtime_readiness",
+            lane: "runtime_readiness",
+            requiresApiKeySecretGrant: false,
+            runnerRepoLocalPath: request.runnerRepoLocalPath,
+        },
+        runtimeIntent: { executionClass: "managed_runtime", applicationRuntimeRequired: true },
+        serverLocal: { repoRoot: request.repoRoot, cleanupWorktrees: true },
+        sandbox: {
+            dispatchAttemptId: request.requestId,
+            executionLeaseId: request.requestId,
+            runnerInstanceId: request.runnerInstanceId,
+            executionMode: "host",
+            executionPolicy: "host_allowed",
+            networkPolicy: { mode: "offline", allowedHosts: [] },
+            requestedResources: {
+                sandboxSlots: 1,
+                cpuMillis: 2000,
+                workerMemoryLimitBytes: 1024 * 1024 * 1024,
+                serviceMemoryLimitBytes: 1024 * 1024 * 1024,
+                runtimeOverheadBytes: 256 * 1024 * 1024,
+                memoryBytes: 2 * 1024 * 1024 * 1024,
+                workspaceBytes: 10 * 1024 * 1024 * 1024,
+                pids: 512,
+                buildSlots: 1,
+            },
+            publicationMode: "shared_filesystem",
+        },
+        artifacts: [],
+    };
+}
+function failedProbe(reasonCode, reasonMessage) {
+    return { status: "failed", reasonCode, reasonMessage, checkedAt: new Date().toISOString() };
+}
+function assertReadinessProbeStartupBudget(expiresAt) {
+    const remainingMs = Date.parse(expiresAt) - Date.now();
+    if (!Number.isFinite(remainingMs) || remainingMs < minimumReadinessProbeStartupBudgetMs) {
+        throw new Error("host_runtime_probe_deadline_insufficient: readiness admission completed too close to the probe deadline; Forge released the reservation before launching the application.");
+    }
+}
+function managedQaLaunchTarget(runtimeContract) {
+    const playwright = runtimeContract.contract.runtime.playwright;
+    if (!playwright)
+        return null;
+    const port = runtimeContract.contract.runtime.ports.find(candidate => candidate.name === playwright.baseUrlPort);
+    return port?.launch && port.baseUrlEnv && port.format
+        ? { managedRuntimePort: port.name, routes: ["/"] }
+        : null;
+}
+function withMaterializedManagedQaTarget(dispatch, hostLease) {
+    const target = dispatch.qaBrowser?.launchTarget;
+    const portName = target?.managed_runtime_port?.trim().toLowerCase();
+    if (!target || !portName)
+        return dispatch;
+    if (!hostLease) {
+        throw new Error("qa_managed_runtime_unavailable: Browser QA requires the verified managed host runtime selected during readiness.");
+    }
+    const normalizedName = portName.toUpperCase().replaceAll(/[^A-Z0-9]/gu, "_");
+    const url = hostLease.environment[`FORGE_${normalizedName}_URL`];
+    if (!url) {
+        throw new Error(`qa_managed_runtime_unavailable: verified runtime port '${portName}' was not launched for this attempt.`);
+    }
+    return {
+        ...dispatch,
+        qaBrowser: dispatch.qaBrowser ? {
+            ...dispatch.qaBrowser,
+            launchTarget: {
+                ...target,
+                url: target.url ?? url,
+                ready_url: target.ready_url ?? url,
+                notes: [target.notes, "Forge launched and verified this URL inside the current fenced attempt."]
+                    .filter(Boolean)
+                    .join(" "),
+            },
+        } : dispatch.qaBrowser,
+    };
+}
+function probeFailureCode(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const candidate = message.split(":", 1)[0]?.trim().toLowerCase() ?? "";
+    return /^[a-z][a-z0-9_.-]{2,159}$/u.test(candidate) ? candidate : "host_runtime_probe_failed";
+}
+function probeFailureMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length > 1000 ? `${message.slice(0, 997)}...` : message;
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw new Error(String(signal.reason ?? "Dispatch cancelled."));