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

package/dist/session/provider-cli/provider-cli.types.d.ts

@@ -1,9 +1,11 @@
 import type { RunOnceDispatchPacket, RunnerDispatchArtifact, RunnerDispatchEvent, RunnerDispatchSpec } from "../session.types.js";
 import type { WorktreeHandle } from "../../worktree/worktree.types.js";
+import type { ProviderProcessRunner } from "./provider-cli.process.js";
 export interface ProviderCliRunContext {
     readonly dispatch: RunOnceDispatchPacket;
     readonly worktree: WorktreeHandle;
     readonly runtimeEnvironment?: Readonly<Record<string, string>>;
+    readonly processRunner?: ProviderProcessRunner;
     readonly signal?: AbortSignal;
     emit(event: RunnerDispatchEvent): Promise<void>;
 }
@@ -11,6 +13,7 @@ export interface ProviderCliDraftContext {
     readonly dispatch: RunOnceDispatchPacket;
     readonly worktree: WorktreeHandle;
     readonly runtimeEnvironment?: Readonly<Record<string, string>>;
+    readonly processRunner?: ProviderProcessRunner;
     readonly signal?: AbortSignal;
     emit(event: RunnerDispatchEvent): Promise<void>;
 }

package/dist/session/provider-cli/provider-output-state.d.ts

@@ -5,6 +5,8 @@ export declare function clip(value: string, maxLength: number): string;
 export interface ProviderOutputState {
     readonly sessionLabel: string | null;
     finalMessage: string | null;
+    /** True only while the provider has reported a tool/command start without a matching completion. */
+    readonly hasActiveToolCall: boolean;
     /** Accumulated provider-reported token usage for this run, or null when none was reported. */
     readonly usage: ProviderUsage | null;
     consume(line: string): readonly RunnerDispatchEvent[];

package/dist/session/provider-cli/provider-output-state.js

@@ -25,12 +25,16 @@ class CursorStreamJsonState {
     finalMessage = null;
     emittedSession = false;
     accumulatedUsage = null;
+    activeToolCallCount = 0;
     get sessionLabel() {
         return this.sessionId ? `session ${this.sessionId}` : null;
     }
     get usage() {
         return this.accumulatedUsage;
     }
+    get hasActiveToolCall() {
+        return this.activeToolCallCount > 0;
+    }
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
@@ -65,6 +69,7 @@ class CursorStreamJsonState {
             const subtype = stringField(event, "subtype");
             const toolCall = objectField(event, "tool_call");
             if (subtype === "started") {
+                this.activeToolCallCount += 1;
                 const summary = formatCursorToolCallStarted(toolCall);
                 if (summary) {
                     return [{
@@ -76,6 +81,7 @@ class CursorStreamJsonState {
                 }
             }
             if (subtype === "completed") {
+                this.activeToolCallCount = Math.max(0, this.activeToolCallCount - 1);
                 const completed = formatCursorToolCallCompleted(toolCall);
                 if (completed) {
                     return [{
@@ -224,18 +230,23 @@ class CodexJsonState {
     finalMessage = null;
     emittedThread = false;
     accumulatedUsage = null;
+    activeToolCallCount = 0;
     get sessionLabel() {
         return this.threadId ? `thread ${this.threadId}` : null;
     }
     get usage() {
         return this.accumulatedUsage;
     }
+    get hasActiveToolCall() {
+        return this.activeToolCallCount > 0;
+    }
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
             return [];
         }
         const type = stringField(event, "type") ?? "";
+        this.trackToolActivity(type, event);
         if (type === "thread.started") {
             this.threadId = stringField(event, "thread_id");
             if (this.threadId && !this.emittedThread) {
@@ -265,7 +276,7 @@ class CodexJsonState {
                     eventType: "provider_cli_error"
                 }];
         }
-        if (type === "item.completed" || type === "item.updated") {
+        if (type === "item.started" || type === "item.completed" || type === "item.updated") {
             const item = objectField(event, "item");
             const itemType = stringField(item, "type");
             if (itemType === "agent_message") {
@@ -287,7 +298,7 @@ class CodexJsonState {
                     return [{
                             role: "worker",
                             kind: "checkpoint",
-                            content: `Codex command ${status || "completed"}: ${clip(command, 500)}`,
+                            content: `Codex command ${status || (type === "item.started" ? "started" : "completed")}: ${clip(command, 500)}`,
                             eventType: "provider_command"
                         }];
                 }
@@ -299,6 +310,23 @@ class CodexJsonState {
         }
         return [];
     }
+    trackToolActivity(type, event) {
+        if (type !== "item.started" && type !== "item.completed") {
+            return;
+        }
+        const item = objectField(event, "item");
+        const itemType = (stringField(item, "type") ?? "").toLowerCase();
+        const toolName = mcpToolName(item);
+        const isTool = itemType === "command_execution"
+            || itemType.includes("mcp")
+            || Boolean(toolName);
+        if (!isTool) {
+            return;
+        }
+        this.activeToolCallCount = type === "item.started"
+            ? this.activeToolCallCount + 1
+            : Math.max(0, this.activeToolCallCount - 1);
+    }
     accumulateUsage(event) {
         const usage = objectField(event, "usage");
         if (Object.keys(usage).length === 0) {

package/dist/session/session.base.d.ts

@@ -1,4 +1,4 @@
-import type { RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchEvent } from "./session.types.js";
+import type { HostRuntimeReadinessProbeRequest, HostRuntimeReadinessProbeResult, RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchEvent } from "./session.types.js";
 import type { HostRuntimeCapacitySnapshot, HostRuntimeReapOptions, HostRuntimeReapReport } from "../runtime/host-runtime-lease.js";
 export interface SessionEventSink {
     emit(event: RunnerDispatchEvent): Promise<void>;
@@ -8,4 +8,5 @@ export interface SessionService {
     updateLease?(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
     reapHostRuntime?(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport | null>;
     runtimeCapacity?(): HostRuntimeCapacitySnapshot | null;
+    probeHostRuntime?(request: HostRuntimeReadinessProbeRequest, signal?: AbortSignal): Promise<HostRuntimeReadinessProbeResult>;
 }

package/dist/session/session.service.d.ts

@@ -1,6 +1,6 @@
 import type { ProviderCliService } from "./provider-cli/provider-cli.base.js";
 import type { SessionEventSink, SessionService } from "./session.base.js";
-import type { RunOnceDispatchPacket, RunOnceResultPacket } from "./session.types.js";
+import type { HostRuntimeReadinessProbeRequest, HostRuntimeReadinessProbeResult, RunOnceDispatchPacket, RunOnceResultPacket } from "./session.types.js";
 import type { WorktreeService } from "../worktree/worktree.base.js";
 import { type HostRuntimeCapacitySnapshot, type HostRuntimeLeaseRuntime, type HostRuntimeReapOptions, type HostRuntimeReapReport } from "../runtime/host-runtime-lease.js";
 export declare class BridgeSessionService implements SessionService {
@@ -11,5 +11,6 @@ export declare class BridgeSessionService implements SessionService {
     updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
     reapHostRuntime(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport | null>;
     runtimeCapacity(): HostRuntimeCapacitySnapshot | null;
+    probeHostRuntime(request: HostRuntimeReadinessProbeRequest, signal?: AbortSignal): Promise<HostRuntimeReadinessProbeResult>;
     runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
 }

package/dist/session/session.service.js

@@ -3,6 +3,8 @@ import { RoutingProviderCliService } from "./provider-cli/provider-cli.service.j
 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;
@@ -23,6 +25,100 @@ export class BridgeSessionService {
     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);
         const redactionSecrets = exactSecrets(dispatch);
@@ -32,7 +128,9 @@ export class BridgeSessionService {
                 return;
             }
             const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
-            events.push(redacted);
+            if (redacted.eventType !== "provider_tool_heartbeat") {
+                events.push(redacted);
+            }
             await sink.emit(redacted);
         };
         const emitLifecycle = async (event) => {
@@ -52,11 +150,25 @@ export class BridgeSessionService {
         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: "Evaluating runner-local managed host admission before preparing the worktree.",
+                    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);
@@ -82,23 +194,28 @@ export class BridgeSessionService {
                     eventType: "host_runtime_admission_acquired",
                 });
             }
-            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
-            });
-            const providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
+            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);
             await emit({
                 role: "runner",
@@ -125,7 +242,7 @@ export class BridgeSessionService {
                     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)),
+                    data: JSON.stringify(hostRuntimeEventResources(hostLease.lease, hostLease.runtimeContract, hostLease.executionClass)),
                 });
                 await emitLifecycle({
                     role: "runner",
@@ -146,16 +263,21 @@ export class BridgeSessionService {
                         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)),
+                        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
                 });
@@ -183,18 +305,32 @@ export class BridgeSessionService {
                 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)
-                    : isCiRepair
-                        ? await this.providerCli.runCiRepair(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 redactRunOnceResultPacket({
@@ -256,6 +392,143 @@ export class BridgeSessionService {
         }
     }
 }
+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."));

package/dist/session/session.types.d.ts

@@ -7,6 +7,7 @@ export interface RunOnceDispatchPacket {
     readonly session: DispatchSession;
     readonly lease: DispatchLease;
     readonly execution: DispatchExecution;
+    readonly runtimeIntent: DispatchRuntimeIntent;
     readonly serverLocal: DispatchServerLocalConfig;
     readonly sandbox?: DispatchSandboxContext | null;
     readonly pullRequest?: DispatchPullRequestContext | null;
@@ -25,6 +26,10 @@ export interface RunOnceDispatchPacket {
     readonly designerRefs?: DispatchDesignerRefHandoffContext | null;
     readonly draft?: DispatchDraftPrompt | null;
 }
+export interface DispatchRuntimeIntent {
+    readonly executionClass: "analysis_only" | "managed_runtime";
+    readonly applicationRuntimeRequired: boolean;
+}
 export interface DispatchSandboxContext {
     readonly dispatchAttemptId: string;
     readonly executionLeaseId: string;
@@ -105,6 +110,7 @@ export interface DispatchQaAppLaunchTarget {
     readonly command?: string | null;
     readonly working_directory?: string | null;
     readonly ready_url?: string | null;
+    readonly managed_runtime_port?: string | null;
     readonly routes: readonly string[];
     readonly notes?: string | null;
 }
@@ -385,4 +391,36 @@ export interface RunnerEventLine {
     readonly event: RunnerDispatchEvent;
 }
 export declare function parseRunOnceDispatchPacket(value: unknown): RunOnceDispatchPacket;
+export interface HostRuntimeReadinessProbeRequest {
+    readonly requestId: string;
+    readonly fencingToken: string;
+    readonly userId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly attempt: number;
+    readonly repoName: string;
+    readonly remoteUrl: string;
+    readonly defaultBranch: string;
+    readonly cloneOnDemand: boolean;
+    readonly runnerRepoLocalPath: string;
+    readonly revision: string;
+    readonly expiresAt: string;
+    readonly repoRoot: string;
+    readonly cleanupWorktrees: boolean;
+}
+export interface HostRuntimeReadinessProbeResult {
+    readonly status: "parallel_ready" | "serialized" | "failed";
+    readonly runtimeContractFingerprint?: string | null;
+    readonly runtimeContractSource?: string | null;
+    readonly reasonCode?: string | null;
+    readonly reasonMessage?: string | null;
+    readonly qaAppLaunchTarget?: HostRuntimeReadinessQaLaunchTarget | null;
+    readonly checkedAt: string;
+}
+export interface HostRuntimeReadinessQaLaunchTarget {
+    readonly managedRuntimePort: string;
+    readonly routes: readonly string[];
+}
 export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[]): RunOnceResultPacket;

package/dist/session/session.types.js

@@ -14,6 +14,7 @@ export function parseRunOnceDispatchPacket(value) {
         session: parseSession(packet.session),
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
+        runtimeIntent: parseRuntimeIntent(packet.runtimeIntent),
         serverLocal: parseServerLocal(packet.serverLocal),
         sandbox: parseSandbox(packet.sandbox, schemaVersion),
         pullRequest: parsePullRequest(packet.pullRequest),
@@ -33,6 +34,21 @@ export function parseRunOnceDispatchPacket(value) {
         draft: parseDraftPrompt(packet.draft)
     };
 }
+function parseRuntimeIntent(value) {
+    if (value === undefined || value === null) {
+        return { executionClass: "managed_runtime", applicationRuntimeRequired: true };
+    }
+    const intent = asObject(value, "runtimeIntent");
+    const executionClass = requiredString(intent, "executionClass").trim().toLowerCase();
+    if (executionClass !== "analysis_only" && executionClass !== "managed_runtime") {
+        throw new Error("runtimeIntent.executionClass must be analysis_only or managed_runtime.");
+    }
+    const applicationRuntimeRequired = requiredBoolean(intent, "applicationRuntimeRequired");
+    if ((executionClass === "analysis_only") === applicationRuntimeRequired) {
+        throw new Error("runtimeIntent execution class and application runtime requirement are inconsistent.");
+    }
+    return { executionClass, applicationRuntimeRequired };
+}
 function parseSandbox(value, schemaVersion) {
     if (value === undefined || value === null) {
         if (schemaVersion === 2) {
@@ -406,6 +422,7 @@ function parseQaAppLaunchTarget(value) {
         command: optionalString(launchTarget, "command"),
         working_directory: optionalString(launchTarget, "working_directory"),
         ready_url: optionalString(launchTarget, "ready_url"),
+        managed_runtime_port: optionalString(launchTarget, "managed_runtime_port"),
         routes: Array.isArray(routes)
             ? routes.map((entry, index) => {
                 if (typeof entry !== "string") {