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

package/dist/bridge/bridge.service.js

@@ -5,19 +5,29 @@ import { randomUUID } from "node:crypto";
 import os from "node:os";
 import { defaultForgeBridgeConfig } from "../config.js";
 import { supportsDraftImageAttachmentsFor } from "../shared/provider-capabilities.js";
-import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
+import { redactText } from "../shared/redaction/redaction.js";
 import { BridgeSessionService } from "../session/session.service.js";
+import { ProcessBackedProviderCliService, RoutingProviderCliService, StreamingProviderProcessRunner, } from "../session/provider-cli/provider-cli.service.js";
+import { redactRunnerDispatchEvent, redactRunOnceResultPacket } from "../session/session-redaction.js";
+import { HostRuntimeLeaseManager } from "../runtime/host-runtime-lease.js";
+import { GitWorktreeService } from "../worktree/worktree.service.js";
+import { RepositoryCoordinatorLock } from "../sandbox/repository-lock.js";
+import { AttemptCoordinatedProviderProcessRunner, AttemptProcessSupervisorRegistry, } from "../runtime/attempt-process-supervisor-registry.js";
 import { failureResult, parseRunOnceDispatchPacket } from "../session/session.types.js";
 import { forgeBridgeVersion } from "../version.js";
 import { canRunDockerMaintenance, DockerPreflight } from "../sandbox/preflight.js";
-import { DockerSandboxRuntime } from "../sandbox/runtime.js";
+import { validateSandboxContract } from "../sandbox/contract.js";
+import { runSandboxProcess } from "../sandbox/process.js";
+import { DockerSandboxRuntime, selectSandboxConfigRefs } from "../sandbox/runtime.js";
 import { codexSandboxProviderAuthAdapter, sandboxProviderAuthAdapterFor, sandboxProviderAuthUnavailableMessage } from "../sandbox/provider-auth/codex.js";
 export class ForgeBridgeService {
     config;
-    sessions;
     connections;
     connection = null;
     heartbeatTimer = null;
+    heartbeatInFlight = false;
+    consecutiveHeartbeatFailures = 0;
+    reconnectingFromHeartbeatFailure = false;
     leaseWatchdogTimer = null;
     sandboxMaintenanceTimer = null;
     sandboxMaintenanceRunning = false;
@@ -25,12 +35,15 @@ export class ForgeBridgeService {
     stopped = false;
     activeSessions = new Map();
     reservations = new Map();
+    activeReadinessProbes = new Map();
     preflight;
     sandboxRuntime;
-    constructor(config, sessions = new BridgeSessionService(), connections = new SignalRBridgeConnectionFactory(), preflight, sandboxRuntime) {
+    sandboxResourceResolver;
+    sessions;
+    constructor(config, sessions = undefined, connections = new SignalRBridgeConnectionFactory(), preflight, sandboxRuntime, sandboxResourceResolver) {
         this.config = config;
-        this.sessions = sessions;
         this.connections = connections;
+        this.sessions = sessions ?? createDefaultSessionService(config.sandboxStateRoot);
         this.preflight = preflight ?? new DockerPreflight({
             dockerExecutable: config.dockerExecutable,
             dockerContext: config.dockerContext,
@@ -40,17 +53,31 @@ export class ForgeBridgeService {
             diskHighWatermarkPercent: config.diskHighWatermarkPercent,
             diskLowWatermarkPercent: config.diskLowWatermarkPercent,
             minimumWorkspaceBytes: config.minimumWorkspaceBytes,
+            hostMemoryReserveBytes: config.sandboxHostMemoryReserveBytes,
+            defaultWorkerMemoryLimitBytes: config.defaultSandboxWorkerMemoryLimitBytes,
+            defaultServiceMemoryLimitBytes: config.defaultSandboxServiceMemoryLimitBytes,
+            runtimeOverheadBytes: config.sandboxRuntimeOverheadBytes,
             requireRootless: config.requireRootlessDocker
         });
         this.sandboxRuntime = sandboxRuntime ?? new DockerSandboxRuntime(config, (request, signal) => this.redeemPublishGrant(request, signal));
+        this.sandboxResourceResolver = sandboxResourceResolver
+            ?? (dispatch => resolveSandboxResourcesFromRepo(dispatch, this.config.sandboxRuntimeOverheadBytes));
     }
     async connectOnce() {
         await this.stopConnection();
         this.stopped = false;
+        const hostReap = await this.sessions.reapHostRuntime?.({
+            runnerId: this.config.runnerId,
+            runnerInstanceId: this.config.runnerInstanceId,
+        });
+        if (hostReap && (hostReap.reaped > 0 || hostReap.degraded > 0)) {
+            logBridgeStatus(`Managed-host recovery reaped ${hostReap.reaped} stale attempt(s), protected ${hostReap.reusedPidsProtected} reused PID(s), and left ${hostReap.degraded} degraded attempt(s) for reconciliation.`);
+        }
         if (this.config.dockerEnabled) {
             const preflight = await this.preflight.refresh();
             if (canReapManagedSandboxes(preflight)) {
                 await this.sandboxRuntime.reap({ diskLow: preflight.diskLow });
+                await this.preflight.refresh();
             }
         }
         const connection = this.connections.create(this.config);
@@ -59,6 +86,7 @@ export class ForgeBridgeService {
             connection.onClose(() => {
                 this.stopHeartbeat();
                 this.abortActiveSessions("bridge connection closed");
+                this.abortActiveReadinessProbes("bridge connection closed");
                 resolve();
             });
         });
@@ -68,6 +96,7 @@ export class ForgeBridgeService {
         connection.onLeaseUpdate?.((request) => this.handleLeaseUpdate(request));
         connection.onCancel((request) => this.handleCancel(request));
         connection.onReap?.((request) => this.handleReap(request));
+        connection.onReadinessProbe?.((request) => this.handleReadinessProbe(request));
         await connection.start();
         await this.invokeAck("Hello", {
             version: this.config.version,
@@ -110,6 +139,7 @@ export class ForgeBridgeService {
         finally {
             if (signal?.aborted) {
                 this.abortActiveSessions(String(signal.reason ?? "bridge stopping"));
+                this.abortActiveReadinessProbes(String(signal.reason ?? "bridge stopping"));
             }
             await this.stopConnection();
         }
@@ -117,6 +147,7 @@ export class ForgeBridgeService {
     async stop() {
         this.stopped = true;
         this.abortActiveSessions("bridge stopping");
+        this.abortActiveReadinessProbes("bridge stopping");
         await this.stopConnection();
         await this.preflight.release();
     }
@@ -174,7 +205,7 @@ export class ForgeBridgeService {
                                 dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
                                 runnerInstanceId: dispatch.sandbox.runnerInstanceId
                             } : {}),
-                            event: redactSecrets(event, redactionSecrets)
+                            event: redactRunnerDispatchEvent(event, redactionSecrets)
                         });
                     }
                     catch (error) {
@@ -192,13 +223,20 @@ export class ForgeBridgeService {
             if (normalized.sandbox?.executionMode === "docker") {
                 await this.flushCleanupReports().catch(() => undefined);
             }
-            await this.sendResult(dispatch, redactSecrets(result, redactionSecrets));
+            await this.sendResult(dispatch, redactRunOnceResultPacket(result, redactionSecrets));
         }
         catch (error) {
             const summary = controller.signal.aborted
                 ? `Dispatch cancelled: ${String(controller.signal.reason ?? "cancelled")}`
                 : redactText(error instanceof Error ? error.message : String(error), redactionSecrets);
-            await this.sendResult(dispatch, failureResult(summary)).catch(() => undefined);
+            const failureEventType = infrastructureFailureEventType(summary);
+            const failureEvents = failureEventType ? [{
+                    role: "runner",
+                    kind: "error",
+                    content: summary,
+                    eventType: failureEventType,
+                }] : [];
+            await this.sendResult(dispatch, failureResult(summary, failureEvents)).catch(() => undefined);
         }
         finally {
             this.activeSessions.delete(leaseId);
@@ -223,7 +261,7 @@ export class ForgeBridgeService {
         }
         if (existing) {
             const sameFence = existing.fencingToken === dispatch.lease.fencingToken;
-            await this.sendOfferDecision(dispatch, sameFence, sameFence ? null : "stale_fence", sameFence ? null : "Offer fence conflicts with the existing reservation.", sameFence ? existing.reservedUntil : null);
+            await this.sendOfferDecision(dispatch, sameFence, sameFence ? null : "stale_fence", sameFence ? null : "Offer fence conflicts with the existing reservation.", sameFence ? existing.reservedUntil : null, sameFence ? existing.resources : null);
             return;
         }
         if (sandbox.runnerInstanceId !== this.config.runnerInstanceId) {
@@ -234,17 +272,24 @@ export class ForgeBridgeService {
             await this.sendOfferDecision(dispatch, false, "lease_expired", "Offer lease is already expired.");
             return;
         }
-        const preflight = this.preflight.current();
+        const preflight = sandbox.executionMode === "docker" && this.config.dockerEnabled
+            ? await this.preflight.run()
+            : this.preflight.current();
         if (sandbox.executionMode === "docker") {
             if (!this.config.dockerEnabled || !preflight?.healthy) {
                 await this.sendOfferDecision(dispatch, false, preflight?.unavailableCode ?? "docker_unavailable", preflight?.unavailableReason ?? "Docker sandbox preflight is unavailable.");
                 return;
             }
-            const networkFailure = sandboxNetworkPolicyFailure(dispatch);
+            const networkFailure = sandboxNetworkPolicyFailure(dispatch, this.config);
             if (networkFailure) {
                 await this.sendOfferDecision(dispatch, false, "policy_mismatch", networkFailure);
                 return;
             }
+            const providerNetworkFailure = sandboxProviderNetworkFailure(dispatch, this.config);
+            if (providerNetworkFailure) {
+                await this.sendOfferDecision(dispatch, false, "provider_network_unavailable", providerNetworkFailure);
+                return;
+            }
             const authFailure = sandboxAuthFailure(dispatch, this.config);
             if (authFailure) {
                 await this.sendOfferDecision(dispatch, false, "sandbox_auth_unavailable", authFailure);
@@ -253,10 +298,24 @@ export class ForgeBridgeService {
         }
         const runtimeState = this.sandboxRuntime.snapshot();
         const usedResources = this.usedSandboxResources(runtimeState.degraded);
-        const capacity = this.sandboxResourceCapacity(preflight);
+        const activeResources = this.activeSandboxResources(runtimeState.degraded);
+        const capacity = this.sandboxResourceCapacity(preflight, activeResources);
+        let requestedResources = sandbox.requestedResources;
+        let sandboxConfigCommitSha = sandbox.sandboxConfigCommitSha ?? null;
+        if (sandbox.executionMode === "docker") {
+            try {
+                const profile = await this.sandboxResourceResolver(this.normalizeDispatch(dispatch));
+                requestedResources = profile.resources;
+                sandboxConfigCommitSha = profile.sandboxConfigCommitSha;
+            }
+            catch (error) {
+                await this.sendOfferDecision(dispatch, false, "sandbox_capacity_profile_unavailable", error instanceof Error ? error.message : "The immutable sandbox contract could not be profiled for admission.");
+                return;
+            }
+        }
         if (sandbox.executionMode === "docker"
-            && !canReserveSandboxResources(usedResources, sandbox.requestedResources, capacity)) {
-            await this.sendOfferDecision(dispatch, false, "capacity_unavailable", "Runner has insufficient sandbox CPU, memory, workspace, PID, build, or slot capacity.");
+            && !canReserveSandboxResources(usedResources, requestedResources, capacity)) {
+            await this.sendOfferDecision(dispatch, false, "capacity_unavailable", sandboxCapacityFailureMessage(usedResources, requestedResources, capacity, preflight, this.config));
             return;
         }
         const reservedUntil = new Date(Math.min(Date.parse(dispatch.lease.expiresAt), Date.now() + 30_000)).toISOString();
@@ -267,9 +326,9 @@ export class ForgeBridgeService {
             expiresAt: dispatch.lease.expiresAt,
             reservedUntil,
             sandboxed: sandbox.executionMode === "docker",
-            resources: sandbox.requestedResources
+            resources: requestedResources
         });
-        await this.sendOfferDecision(dispatch, true, null, null, reservedUntil);
+        await this.sendOfferDecision(dispatch, true, null, null, reservedUntil, requestedResources, sandboxConfigCommitSha);
     }
     async handleStart(rawDispatch) {
         const envelope = parseStartEnvelope(rawDispatch);
@@ -315,6 +374,10 @@ export class ForgeBridgeService {
             await this.sendResult(dispatch, failureResult("Start rejected because the provider secret grant handle is missing.")).catch(() => undefined);
             return;
         }
+        dispatch = {
+            ...dispatch,
+            sandbox: { ...dispatch.sandbox, requestedResources: reservation.resources },
+        };
         this.reservations.delete(envelope.dispatchAttemptId);
         await this.handleDispatch(dispatch);
     }
@@ -355,10 +418,15 @@ export class ForgeBridgeService {
         const active = this.activeSessions.get(request.leaseId);
         if (active && active.fencingToken === request.fencingToken && active.dispatchAttemptId === request.dispatchAttemptId) {
             active.leaseExpiresAt = request.expiresAt;
-            await this.sandboxRuntime.updateLease(request.dispatchAttemptId, request.fencingToken, request.expiresAt);
+            if (active.sandboxed) {
+                await this.sandboxRuntime.updateLease(request.dispatchAttemptId, request.fencingToken, request.expiresAt);
+            }
+            else {
+                await this.sessions.updateLease?.(request.dispatchAttemptId, request.fencingToken, request.expiresAt);
+            }
         }
     }
-    async sendOfferDecision(dispatch, accepted, code = null, message = null, reservedUntil = null) {
+    async sendOfferDecision(dispatch, accepted, code = null, message = null, reservedUntil = null, reservedResources = null, sandboxConfigCommitSha = null) {
         if (!dispatch.sandbox)
             return;
         const payload = {
@@ -369,7 +437,9 @@ export class ForgeBridgeService {
             accepted,
             code,
             message,
-            reservedUntil: accepted ? reservedUntil ?? dispatch.lease.expiresAt : null
+            reservedUntil: accepted ? reservedUntil ?? dispatch.lease.expiresAt : null,
+            reservedResources: accepted ? reservedResources : null,
+            sandboxConfigCommitSha: accepted ? sandboxConfigCommitSha : null,
         };
         await this.invokeAck("OfferDecision", payload);
     }
@@ -402,19 +472,73 @@ export class ForgeBridgeService {
         active.controller.abort(request.reason ?? "cancelled by server");
     }
     async handleReap(request) {
-        if (!this.config.dockerEnabled
-            || request.runnerId !== this.config.runnerId
+        if (request.runnerId !== this.config.runnerId
             || request.runnerInstanceId !== this.config.runnerInstanceId)
             return;
         await this.runSandboxMaintenance();
         await this.sendHeartbeat();
     }
+    async handleReadinessProbe(rawRequest) {
+        const request = parseReadinessProbe(rawRequest);
+        if (!request || request.runnerInstanceId !== this.config.runnerInstanceId)
+            return;
+        const existing = this.activeReadinessProbes.get(request.requestId);
+        if (existing)
+            return;
+        const controller = new AbortController();
+        this.activeReadinessProbes.set(request.requestId, controller);
+        const deadlineMs = Date.parse(request.expiresAt) - Date.now();
+        const timer = setTimeout(() => controller.abort("readiness probe expired"), Math.max(0, deadlineMs));
+        timer.unref?.();
+        let result;
+        try {
+            if (!this.sessions.probeHostRuntime) {
+                throw new Error("host_runtime_probe_unavailable: this bridge does not implement runtime readiness probes.");
+            }
+            const probe = await this.sessions.probeHostRuntime({
+                ...request,
+                runnerId: this.config.runnerId,
+                repoRoot: this.config.defaultRepoRoot,
+                cleanupWorktrees: this.config.cleanupWorktrees,
+            }, controller.signal);
+            result = {
+                schemaVersion: 1,
+                requestId: request.requestId,
+                fencingToken: request.fencingToken,
+                runnerInstanceId: this.config.runnerInstanceId,
+                ...probe,
+            };
+        }
+        catch (error) {
+            result = {
+                schemaVersion: 1,
+                requestId: request.requestId,
+                fencingToken: request.fencingToken,
+                runnerInstanceId: this.config.runnerInstanceId,
+                status: "failed",
+                reasonCode: "host_runtime_probe_failed",
+                reasonMessage: errorMessage(error).slice(0, 1000),
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+            this.activeReadinessProbes.delete(request.requestId);
+        }
+        await this.invokeAck("ReadinessResult", result).catch(() => undefined);
+        await this.sendHeartbeat().catch(() => undefined);
+    }
     abortActiveSessions(reason) {
         for (const active of this.activeSessions.values()) {
             active.controller.abort(reason);
         }
         this.activeSessions.clear();
     }
+    abortActiveReadinessProbes(reason) {
+        for (const controller of this.activeReadinessProbes.values())
+            controller.abort(reason);
+        this.activeReadinessProbes.clear();
+    }
     normalizeDispatch(dispatch) {
         const mapping = findRepoMapping(dispatch, repoMappingsFor(this.config));
         const localPath = mapping?.localPath?.trim();
@@ -465,12 +589,41 @@ export class ForgeBridgeService {
     }
     startHeartbeat() {
         this.stopHeartbeat();
+        this.consecutiveHeartbeatFailures = 0;
+        this.reconnectingFromHeartbeatFailure = false;
         const intervalMs = positiveFiniteNumber(this.config.heartbeatIntervalMs, 30_000);
         this.heartbeatTimer = setInterval(() => {
-            this.sendHeartbeat().catch(() => undefined);
+            void this.heartbeatTick();
         }, intervalMs);
         this.heartbeatTimer.unref?.();
     }
+    async heartbeatTick() {
+        if (this.heartbeatInFlight || this.reconnectingFromHeartbeatFailure)
+            return;
+        const connection = this.connection;
+        if (!connection)
+            return;
+        this.heartbeatInFlight = true;
+        try {
+            await this.sendHeartbeat();
+            this.consecutiveHeartbeatFailures = 0;
+        }
+        catch (error) {
+            if (connection !== this.connection || this.stopped)
+                return;
+            this.consecutiveHeartbeatFailures += 1;
+            logBridgeStatus(`Heartbeat ${this.consecutiveHeartbeatFailures} failed: ${errorMessage(error)}.`);
+            if (this.consecutiveHeartbeatFailures < 2)
+                return;
+            this.reconnectingFromHeartbeatFailure = true;
+            this.stopHeartbeat();
+            logBridgeStatus("Heartbeat failed twice. Closing the stale connection so the Bridge can reconnect...");
+            await connection.stop().catch(() => undefined);
+        }
+        finally {
+            this.heartbeatInFlight = false;
+        }
+    }
     startLeaseWatchdog() {
         this.stopLeaseWatchdog();
         this.leaseWatchdogTimer = setInterval(() => this.expireLeases(), 1000);
@@ -503,8 +656,6 @@ export class ForgeBridgeService {
     }
     startSandboxMaintenance() {
         this.stopSandboxMaintenance();
-        if (!this.config.dockerEnabled)
-            return;
         this.sandboxMaintenanceTimer = setInterval(() => {
             this.runSandboxMaintenance().catch(() => undefined);
         }, 60_000);
@@ -521,11 +672,20 @@ export class ForgeBridgeService {
             return;
         this.sandboxMaintenanceRunning = true;
         try {
-            const preflight = await this.preflight.refresh();
-            if (canReapManagedSandboxes(preflight)) {
-                const attemptSnapshot = await this.readAttemptSnapshot();
-                await this.sandboxRuntime.reap({ diskLow: preflight.diskLow, attemptSnapshot });
-                await this.flushCleanupReports();
+            const hostReap = await this.sessions.reapHostRuntime?.({
+                runnerId: this.config.runnerId,
+                runnerInstanceId: this.config.runnerInstanceId,
+            });
+            if (hostReap && (hostReap.reaped > 0 || hostReap.degraded > 0)) {
+                logBridgeStatus(`Managed-host maintenance reaped ${hostReap.reaped} stale attempt(s) and left ${hostReap.degraded} degraded attempt(s) for reconciliation.`);
+            }
+            if (this.config.dockerEnabled) {
+                const preflight = await this.preflight.refresh();
+                if (canReapManagedSandboxes(preflight)) {
+                    const attemptSnapshot = await this.readAttemptSnapshot();
+                    await this.sandboxRuntime.reap({ diskLow: preflight.diskLow, attemptSnapshot });
+                    await this.flushCleanupReports();
+                }
             }
         }
         finally {
@@ -568,7 +728,8 @@ export class ForgeBridgeService {
         const runtimeState = this.sandboxRuntime.snapshot();
         const reserved = [...this.reservations.values()].filter(reservation => reservation.sandboxed).length;
         const used = this.usedSandboxResources(runtimeState.degraded);
-        const capacity = this.sandboxResourceCapacity(preflight);
+        const activeResources = this.activeSandboxResources(runtimeState.degraded);
+        const capacity = this.sandboxResourceCapacity(preflight, activeResources);
         return {
             schemaVersion: 3,
             activeSessionCount: this.activeSessions.size,
@@ -580,7 +741,7 @@ export class ForgeBridgeService {
             sandboxProfiles: this.config.sandboxProfiles,
             runnerInstanceId: this.config.runnerInstanceId,
             trustDomainId: this.config.trustDomainId,
-            maxConcurrentSandboxes: preflight?.maxConcurrentSandboxes ?? 0,
+            maxConcurrentSandboxes: capacity.sandboxSlots,
             reservedSandboxCount: reserved,
             activeSandboxCount: runtimeState.active,
             startingSandboxCount: runtimeState.starting,
@@ -588,6 +749,7 @@ export class ForgeBridgeService {
             sandboxRuntimes: preflight?.healthy ? ["docker"] : [],
             sandboxRuntimeVersion: preflight?.runtimeVersion ?? null,
             sandboxFeatures: preflight?.features ?? null,
+            allowsOpenPublicSandbox: this.config.allowOpenPublicSandbox,
             sandboxPublicationModes: [this.config.sandboxPublicationMode ?? "shared_filesystem"],
             sandboxAuthModes: sandboxAuthModesFor(this.config),
             availableMemoryBytes: preflight ? Math.max(0, capacity.memoryBytes - used.memoryBytes) : null,
@@ -597,6 +759,17 @@ export class ForgeBridgeService {
             preflightGeneration: preflight?.generation ?? 0,
             sandboxUnavailableCode: this.config.dockerEnabled ? preflight?.unavailableCode ?? null : "docker_disabled",
             sandboxUnavailableReason: this.config.dockerEnabled ? preflight?.unavailableReason ?? null : "Docker sandboxing is disabled by runner configuration.",
+            sandboxMemoryCapacity: preflight ? {
+                defaultWorkerMemoryLimitBytes: this.config.defaultSandboxWorkerMemoryLimitBytes,
+                defaultServiceMemoryLimitBytes: this.config.defaultSandboxServiceMemoryLimitBytes,
+                runtimeOverheadBytes: this.config.sandboxRuntimeOverheadBytes,
+                hostReserveBytes: preflight.hostReserveBytes,
+                activeReservationBytes: used.memoryBytes,
+                daemonTotalBytes: preflight.totalMemoryBytes,
+                daemonAvailableBytes: preflight.availableMemoryBytes,
+                availableForAdmissionBytes: Math.max(0, capacity.memoryBytes - used.memoryBytes),
+            } : null,
+            hostRuntime: this.sessions.runtimeCapacity?.() ?? null,
             supportsApiSecretGrant: this.config.supportsApiSecretGrant,
             supportsManagedWorktrees: this.config.supportsManagedWorktrees,
             supportsManagedForgeArtifacts: this.config.supportsManagedForgeArtifacts,
@@ -618,14 +791,32 @@ export class ForgeBridgeService {
         ];
         return sumSandboxResources(resources);
     }
-    sandboxResourceCapacity(preflight) {
+    activeSandboxResources(degradedReservations) {
+        return sumSandboxResources([
+            ...[...this.activeSessions.values()]
+                .filter(session => session.sandboxed)
+                .map(session => session.resources),
+            ...Array.from({ length: degradedReservations }, () => defaultSandboxResources())
+        ]);
+    }
+    sandboxResourceCapacity(preflight, activeResources) {
         if (!preflight)
             return zeroSandboxResources();
         return {
-            sandboxSlots: preflight.maxConcurrentSandboxes,
+            // Host free memory and disk already reflect active containers. Add their
+            // commitments back to form a stable total capacity, then subtract them
+            // exactly once in usedSandboxResources.
+            sandboxSlots: Math.min(this.config.maxConcurrentSandboxes, preflight.maxConcurrentSandboxes + activeResources.sandboxSlots),
             cpuMillis: preflight.availableCpuMillis,
-            memoryBytes: Math.max(0, preflight.availableMemoryBytes - 2 * 1024 ** 3),
-            workspaceBytes: Math.max(0, preflight.availableWorkspaceBytes - this.config.minimumWorkspaceBytes),
+            workerMemoryLimitBytes: 0,
+            serviceMemoryLimitBytes: 0,
+            runtimeOverheadBytes: 0,
+            memoryBytes: Math.max(0, preflight.availableMemoryBytes
+                - (this.config.sandboxHostMemoryReserveBytes ?? 2 * 1024 ** 3)
+                + activeResources.memoryBytes),
+            workspaceBytes: Math.max(0, preflight.availableWorkspaceBytes
+                - this.config.minimumWorkspaceBytes
+                + activeResources.workspaceBytes),
             pids: this.config.sandboxPidCapacity,
             buildSlots: this.config.maxConcurrentSandboxBuilds
         };
@@ -671,6 +862,12 @@ function isDispatchNoLongerPending(error) {
     }
     return error instanceof Error && error.message === "Dispatch is no longer pending.";
 }
+function createDefaultSessionService(sandboxStateRoot) {
+    const rawProcessRunner = new StreamingProviderProcessRunner();
+    const processSupervisors = new AttemptProcessSupervisorRegistry();
+    const coordinatedProcessRunner = new AttemptCoordinatedProviderProcessRunner(processSupervisors, rawProcessRunner);
+    return new BridgeSessionService(new GitWorktreeService(undefined, new RepositoryCoordinatorLock(sandboxStateRoot)), new RoutingProviderCliService(new ProcessBackedProviderCliService(coordinatedProcessRunner)), new HostRuntimeLeaseManager(sandboxStateRoot, undefined, undefined, processSupervisors, rawProcessRunner));
+}
 export class SignalRBridgeConnectionFactory {
     create(config) {
         return new SignalRBridgeConnection(config);
@@ -738,6 +935,11 @@ export class SignalRBridgeConnection {
             void handler(request).catch(() => undefined);
         });
     }
+    onReadinessProbe(handler) {
+        this.connection.on("ReadinessProbe", (request) => {
+            void handler(request).catch(() => undefined);
+        });
+    }
     invoke(methodName, payload) {
         return this.connection.invoke(methodName, payload);
     }
@@ -745,6 +947,9 @@ export class SignalRBridgeConnection {
 export function defaultBridgeServiceConfig(overrides = {}) {
     const defaults = defaultForgeBridgeConfig();
     const cliProviders = splitCsv(process.env.FORGE_CLI_PROVIDERS ?? "codex");
+    const sandboxHostMemoryReserveDefault = process.platform === "linux"
+        ? 2 * 1024 ** 3
+        : 1024 ** 3;
     const sandboxPublicationMode = process.env.FORGE_SANDBOX_PUBLICATION_MODE === "bridge_push" ? "bridge_push" : "shared_filesystem";
     const config = {
         serverUrl: process.env.FORGE_URL ?? "http://localhost:5208",
@@ -755,6 +960,7 @@ export function defaultBridgeServiceConfig(overrides = {}) {
         maxConcurrentSandboxBuilds: positiveFiniteNumber(Number(process.env.FORGE_MAX_CONCURRENT_SANDBOX_BUILDS ?? 1), 1),
         sandboxPidCapacity: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_PID_CAPACITY ?? 2048), 2048),
         dockerEnabled: process.env.FORGE_DOCKER_SANDBOX !== "false",
+        allowOpenPublicSandbox: process.env.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX === "true",
         sandboxPublicationMode,
         dockerExecutable: process.env.FORGE_DOCKER_EXECUTABLE ?? "docker",
         dockerContext: process.env.FORGE_DOCKER_CONTEXT ?? "",
@@ -763,6 +969,11 @@ export function defaultBridgeServiceConfig(overrides = {}) {
         diskHighWatermarkPercent: positiveFiniteNumber(Number(process.env.FORGE_DISK_HIGH_WATERMARK_PERCENT ?? 85), 85),
         diskLowWatermarkPercent: positiveFiniteNumber(Number(process.env.FORGE_DISK_LOW_WATERMARK_PERCENT ?? 75), 75),
         minimumWorkspaceBytes: positiveFiniteNumber(Number(process.env.FORGE_MINIMUM_WORKSPACE_BYTES ?? 10 * 1024 ** 3), 10 * 1024 ** 3),
+        sandboxHostMemoryReserveBytes: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_HOST_MEMORY_RESERVE_BYTES ?? sandboxHostMemoryReserveDefault), sandboxHostMemoryReserveDefault),
+        defaultSandboxWorkerMemoryLimitBytes: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_DEFAULT_WORKER_MEMORY_LIMIT_BYTES ?? 2 * 1024 ** 3), 2 * 1024 ** 3),
+        defaultSandboxServiceMemoryLimitBytes: nonNegativeFiniteNumber(Number(process.env.FORGE_SANDBOX_DEFAULT_SERVICE_MEMORY_LIMIT_BYTES ?? 0), 0),
+        sandboxRuntimeOverheadBytes: Math.max(128 * 1024 ** 2, nonNegativeFiniteNumber(Number(process.env.FORGE_SANDBOX_RUNTIME_OVERHEAD_BYTES ?? 128 * 1024 ** 2), 128 * 1024 ** 2)),
+        sandboxMemorySampleIntervalMs: Math.min(30_000, Math.max(250, positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_MEMORY_SAMPLE_INTERVAL_MS ?? 1000), 1000))),
         imageRetentionCount: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_IMAGE_RETENTION_COUNT ?? 3), 3),
         imageRetentionTtlMs: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_IMAGE_RETENTION_TTL_MS ?? 7 * 24 * 60 * 60 * 1000), 7 * 24 * 60 * 60 * 1000),
         auditRetentionCount: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_AUDIT_RETENTION_COUNT ?? 200), 200),
@@ -811,6 +1022,9 @@ function normalizeServerUrl(serverUrl) {
 function positiveFiniteNumber(value, fallback) {
     return Number.isFinite(value) && value > 0 ? value : fallback;
 }
+function nonNegativeFiniteNumber(value, fallback) {
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
 function providerStatusesFor(providers) {
     return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "", models: configuredModelsFor(provider) }]));
 }
@@ -932,10 +1146,11 @@ function normalizeQaAppLaunchTarget(target) {
         command: cleanString(target.command),
         working_directory: cleanString(target.working_directory),
         ready_url: cleanString(target.ready_url),
+        managed_runtime_port: cleanString(target.managed_runtime_port),
         routes,
         notes: cleanString(target.notes)
     };
-    return normalized.url || normalized.command || normalized.ready_url || routes.length > 0
+    return normalized.url || normalized.command || normalized.ready_url || normalized.managed_runtime_port
         ? normalized
         : null;
 }
@@ -1004,12 +1219,12 @@ function abortPromise(signal) {
 export function canReapManagedSandboxes(preflight) {
     return canRunDockerMaintenance(preflight);
 }
-function sandboxNetworkPolicyFailure(dispatch) {
+function sandboxNetworkPolicyFailure(dispatch, config) {
     const sandbox = dispatch.sandbox;
     if (!sandbox)
         return "Protocol-v2 sandbox context is missing.";
     if (sandbox.networkPolicy.mode === "open_public"
-        && (sandbox.executionPolicy === "sandbox_required" || process.env.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX !== "true")) {
+        && (sandbox.executionPolicy === "sandbox_required" || !config.allowOpenPublicSandbox)) {
         return "open_public sandbox networking is not permitted by this runner policy.";
     }
     if (sandbox.networkPolicy.mode === "public_allowlist"
@@ -1019,6 +1234,61 @@ function sandboxNetworkPolicyFailure(dispatch) {
     }
     return null;
 }
+function infrastructureFailureEventType(summary) {
+    if (summary.startsWith("worktree_prepare_failed:"))
+        return "worktree_prepare_failed";
+    if (summary.startsWith("provider_start_unavailable:"))
+        return "provider_start_unavailable";
+    if (summary.startsWith("host_port_collision:"))
+        return "host_port_collision";
+    if (summary.startsWith("host_runtime_process_exited:"))
+        return "host_runtime_process_exited";
+    if (summary.startsWith("host_runtime_listener_timeout:"))
+        return "host_runtime_listener_timeout";
+    if (summary.startsWith("host_runtime_http_readiness_timeout:"))
+        return "host_runtime_http_readiness_timeout";
+    if (summary.startsWith("attempt_process_supervisor_start_failed:"))
+        return "attempt_process_supervisor_start_failed";
+    if (summary.startsWith("attempt_process_supervisor_start_timeout:"))
+        return "attempt_process_supervisor_start_timeout";
+    return null;
+}
+function parseReadinessProbe(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const request = value;
+    const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+    const bounded = (candidate, maximum) => typeof candidate === "string" && candidate.trim().length > 0 && candidate.length <= maximum;
+    if (request.schemaVersion !== 1
+        || !uuid.test(request.requestId ?? "")
+        || !uuid.test(request.fencingToken ?? "")
+        || !uuid.test(request.userId ?? "")
+        || !uuid.test(request.projectId ?? "")
+        || !uuid.test(request.repoId ?? "")
+        || !uuid.test(request.runnerInstanceId ?? "")
+        || !Number.isInteger(request.attempt) || (request.attempt ?? 0) < 1
+        || !bounded(request.repoName, 160)
+        || typeof request.remoteUrl !== "string" || request.remoteUrl.length > 2048
+        || !bounded(request.defaultBranch, 512)
+        || typeof request.cloneOnDemand !== "boolean"
+        || !bounded(request.runnerRepoLocalPath, 4096)
+        || !bounded(request.revision, 512)
+        || !Number.isFinite(Date.parse(request.expiresAt ?? ""))
+        || Date.parse(request.expiresAt ?? "") <= Date.now()) {
+        return null;
+    }
+    return request;
+}
+function sandboxProviderNetworkFailure(dispatch, config) {
+    const sandbox = dispatch.sandbox;
+    if (!sandbox || sandbox.networkPolicy.mode !== "offline")
+        return null;
+    const provider = dispatch.execution.provider.trim().toLowerCase();
+    const isNetworkProvider = config.cliProviders.some(candidate => candidate.trim().toLowerCase() === provider);
+    if (!isNetworkProvider)
+        return null;
+    return `Provider ${dispatch.execution.provider} requires outbound network access, but this Docker attempt uses the offline network policy.`;
+}
 function sandboxAuthFailure(dispatch, config) {
     const unsupported = sandboxProviderAuthUnavailableMessage(dispatch.execution.provider, dispatch.execution.authKind);
     if (unsupported) {
@@ -1046,10 +1316,51 @@ export function canReserveSandboxResources(used, requested, capacity) {
         && used.pids + requested.pids <= capacity.pids
         && used.buildSlots + requested.buildSlots <= capacity.buildSlots;
 }
+export function sandboxCapacityFailureMessage(used, requested, capacity, preflight, config) {
+    const availableSlots = Math.max(0, capacity.sandboxSlots - used.sandboxSlots);
+    if (requested.sandboxSlots > availableSlots) {
+        return `Sandbox slot capacity is insufficient: requested ${requested.sandboxSlots}, available ${availableSlots}, ${used.sandboxSlots} already reserved.`;
+    }
+    const availableMemoryBytes = Math.max(0, capacity.memoryBytes - used.memoryBytes);
+    if (requested.memoryBytes > availableMemoryBytes) {
+        return [
+            `Sandbox memory capacity is insufficient: requested ${formatBytes(requested.memoryBytes)} total`,
+            `(worker ${formatBytes(requested.workerMemoryLimitBytes)}, services ${formatBytes(requested.serviceMemoryLimitBytes)}, runtime overhead ${formatBytes(requested.runtimeOverheadBytes)}),`,
+            `but ${formatBytes(availableMemoryBytes)} is available for admission.`,
+            `Docker reports ${formatBytes(preflight?.availableMemoryBytes ?? 0)} available of ${formatBytes(preflight?.totalMemoryBytes ?? 0)};`,
+            `Forge reserves ${formatBytes(preflight?.hostReserveBytes ?? config.sandboxHostMemoryReserveBytes ?? 0)} for the host and tracks ${formatBytes(used.memoryBytes)} in active or reserved attempts.`,
+        ].join(" ");
+    }
+    const availableCpuMillis = Math.max(0, capacity.cpuMillis - used.cpuMillis);
+    if (requested.cpuMillis > availableCpuMillis) {
+        return `Sandbox CPU capacity is insufficient: requested ${requested.cpuMillis} millis, available ${availableCpuMillis} millis, ${used.cpuMillis} millis already reserved.`;
+    }
+    const availableWorkspaceBytes = Math.max(0, capacity.workspaceBytes - used.workspaceBytes);
+    if (requested.workspaceBytes > availableWorkspaceBytes) {
+        return `Sandbox workspace capacity is insufficient: requested ${formatBytes(requested.workspaceBytes)}, available ${formatBytes(availableWorkspaceBytes)}, ${formatBytes(used.workspaceBytes)} already reserved.`;
+    }
+    const availablePids = Math.max(0, capacity.pids - used.pids);
+    if (requested.pids > availablePids) {
+        return `Sandbox PID capacity is insufficient: requested ${requested.pids}, available ${availablePids}, ${used.pids} already reserved.`;
+    }
+    const availableBuildSlots = Math.max(0, capacity.buildSlots - used.buildSlots);
+    return `Sandbox build capacity is insufficient: requested ${requested.buildSlots}, available ${availableBuildSlots}, ${used.buildSlots} already reserved.`;
+}
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return "0 B";
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    const power = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / 1024 ** power;
+    return `${value >= 10 || power === 0 ? value.toFixed(0) : value.toFixed(2)} ${units[power]}`;
+}
 function sumSandboxResources(resources) {
     return resources.reduce((total, resource) => ({
         sandboxSlots: total.sandboxSlots + resource.sandboxSlots,
         cpuMillis: total.cpuMillis + resource.cpuMillis,
+        workerMemoryLimitBytes: total.workerMemoryLimitBytes + resource.workerMemoryLimitBytes,
+        serviceMemoryLimitBytes: total.serviceMemoryLimitBytes + resource.serviceMemoryLimitBytes,
+        runtimeOverheadBytes: total.runtimeOverheadBytes + resource.runtimeOverheadBytes,
         memoryBytes: total.memoryBytes + resource.memoryBytes,
         workspaceBytes: total.workspaceBytes + resource.workspaceBytes,
         pids: total.pids + resource.pids,
@@ -1057,18 +1368,83 @@ function sumSandboxResources(resources) {
     }), zeroSandboxResources());
 }
 function zeroSandboxResources() {
-    return { sandboxSlots: 0, cpuMillis: 0, memoryBytes: 0, workspaceBytes: 0, pids: 0, buildSlots: 0 };
+    return {
+        sandboxSlots: 0,
+        cpuMillis: 0,
+        workerMemoryLimitBytes: 0,
+        serviceMemoryLimitBytes: 0,
+        runtimeOverheadBytes: 0,
+        memoryBytes: 0,
+        workspaceBytes: 0,
+        pids: 0,
+        buildSlots: 0,
+    };
 }
 function defaultSandboxResources() {
     return {
         sandboxSlots: 1,
         cpuMillis: 2000,
-        memoryBytes: 2 * 1024 ** 3,
+        workerMemoryLimitBytes: 2 * 1024 ** 3,
+        serviceMemoryLimitBytes: 0,
+        runtimeOverheadBytes: 128 * 1024 ** 2,
+        memoryBytes: 2 * 1024 ** 3 + 128 * 1024 ** 2,
         workspaceBytes: 10 * 1024 ** 3,
         pids: 512,
         buildSlots: 0
     };
 }
+export function resolveDynamicSandboxResources(requested, serviceCount, networkMode, baseRuntimeOverheadBytes = 128 * 1024 ** 2) {
+    const serviceMemoryLimitBytes = Math.max(0, serviceCount) * 1024 ** 3;
+    const runtimeOverheadBytes = Math.max(128 * 1024 ** 2, baseRuntimeOverheadBytes)
+        + (networkMode === "public_allowlist" ? 256 * 1024 ** 2 : 0);
+    return {
+        ...requested,
+        serviceMemoryLimitBytes,
+        runtimeOverheadBytes,
+        memoryBytes: requested.workerMemoryLimitBytes + serviceMemoryLimitBytes + runtimeOverheadBytes,
+    };
+}
+export async function resolveSandboxResourcesFromRepo(dispatch, baseRuntimeOverheadBytes = 128 * 1024 ** 2) {
+    const repoPath = dispatch.repo.serverLocalPath;
+    const sandbox = dispatch.sandbox;
+    if (!repoPath || !sandbox) {
+        throw new Error("Sandbox admission needs a mapped repository.");
+    }
+    const selection = selectSandboxConfigRefs(sandbox.executionPolicy, sandbox.sandboxConfigCommitSha, dispatch.repo.defaultBranch);
+    const configCommitSha = await resolveFirstGitCommit(repoPath, selection.refs);
+    if (!configCommitSha) {
+        throw new Error("Sandbox admission could not resolve the immutable sandbox config commit.");
+    }
+    const contractResult = await runSandboxProcess({
+        command: "git",
+        args: ["-C", repoPath, "show", `${configCommitSha}:.forge/forge.sandbox.yml`],
+        timeoutMs: 30_000,
+        maxOutputBytes: 1024 * 1024,
+    });
+    if (contractResult.exitCode !== 0) {
+        throw new Error("The approved immutable sandbox contract is unavailable in the mapped repository.");
+    }
+    const contract = validateSandboxContract(contractResult.stdout);
+    return {
+        resources: resolveDynamicSandboxResources(sandbox.requestedResources, contract.contract.services.length, sandbox.networkPolicy.mode, baseRuntimeOverheadBytes),
+        sandboxConfigCommitSha: configCommitSha,
+    };
+}
+async function resolveFirstGitCommit(repoPath, refs) {
+    for (const ref of refs) {
+        const result = await runSandboxProcess({
+            command: "git",
+            args: ["-C", repoPath, "rev-parse", "--verify", `${ref}^{commit}`],
+            timeoutMs: 30_000,
+            maxOutputBytes: 1024 * 1024,
+        });
+        const commitSha = result.stdout.trim().toLowerCase();
+        if (result.exitCode === 0 && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(commitSha)) {
+            return commitSha;
+        }
+    }
+    return null;
+}
 function parseOfferEnvelope(value) {
     return parseDispatchEnvelope(value);
 }