@loucompanion/forge-bridge 0.1.3-dev.9bc5014a2270 → 0.1.3-dev.a58d7cd1092f

package/dist/bridge/bridge.service.js

@@ -1,47 +1,203 @@
 import { HubConnectionBuilder, HttpTransportType, LogLevel } from "@microsoft/signalr";
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
 import { defaultForgeBridgeConfig } from "../config.js";
-import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
+import { supportsDraftImageAttachmentsFor } from "../shared/provider-capabilities.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 { buildMemoryAdmissionDiagnostics } from "../runtime/memory-capacity.js";
+import { DockerEngineProbe } from "../runtime/docker-engine-probe.js";
+import { estimateWorkspaceBytesFromRepo } from "../runtime/workspace-resource-estimator.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 { 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";
+import { formatBytes } from "../shared/format/format-bytes.js";
+import { emptyRunnerHostCapabilitySnapshot, ProcessRunnerHostCapabilityProbe, } from "./runner-host-capabilities.js";
+/**
+ * Protocol-v2 events are acknowledged one at a time before runOnce returns.
+ * Sending the complete transcript again in DispatchResult made long QA and CI
+ * sessions exceed SignalR's receive limit, disconnecting the bridge after the
+ * provider had already completed. The API combines its acknowledged streamed
+ * events with the terminal result, so the callback only needs the outcome and
+ * artifacts. Protocol v1 retains the transcript for legacy servers.
+ */
+export function compactTerminalResult(dispatch, result) {
+    return dispatch.schemaVersion >= 2 && result.events.length > 0
+        ? { ...result, events: [] }
+        : result;
+}
 export class ForgeBridgeService {
     config;
-    sessions;
     connections;
+    hostCapabilityProbe;
     connection = null;
     heartbeatTimer = null;
+    heartbeatInFlight = false;
+    consecutiveHeartbeatFailures = 0;
+    reconnectingFromHeartbeatFailure = false;
+    leaseWatchdogTimer = null;
+    sandboxMaintenanceTimer = null;
+    sandboxMaintenanceRunning = false;
     closed = null;
+    transportRecovery = null;
+    transportRecoveryGeneration = 0;
     stopped = false;
     activeSessions = new Map();
-    constructor(config, sessions = new BridgeSessionService(), connections = new SignalRBridgeConnectionFactory()) {
+    reservations = new Map();
+    activeReadinessProbes = new Map();
+    preflight;
+    dockerEngineProbe;
+    sandboxRuntime;
+    sandboxResourceResolver;
+    sessions;
+    sandboxAmbientMemoryCommitmentBytes = null;
+    hostCapabilities = emptyRunnerHostCapabilitySnapshot();
+    hostCapabilitiesDetected = false;
+    constructor(config, sessions = undefined, connections = new SignalRBridgeConnectionFactory(), preflight, sandboxRuntime, sandboxResourceResolver, dockerEngineProbe, hostCapabilityProbe = new ProcessRunnerHostCapabilityProbe()) {
         this.config = config;
-        this.sessions = sessions;
         this.connections = connections;
+        this.hostCapabilityProbe = hostCapabilityProbe;
+        this.sessions = sessions ?? createDefaultSessionService(config.sandboxStateRoot);
+        this.preflight = preflight ?? new DockerPreflight({
+            dockerExecutable: config.dockerExecutable,
+            dockerContext: config.dockerContext,
+            stateRoot: config.sandboxStateRoot,
+            runnerInstanceId: config.runnerInstanceId,
+            maxConcurrentSandboxes: config.maxConcurrentSandboxes,
+            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.dockerEngineProbe = dockerEngineProbe ?? new DockerEngineProbe({
+            dockerExecutable: config.dockerExecutable,
+            dockerContext: config.dockerContext,
+            recovery: {
+                enabled: config.dockerDesktopRecoveryEnabled,
+                failureThreshold: config.dockerRecoveryFailureThreshold,
+                cooldownMs: config.dockerRecoveryCooldownMs,
+                startupTimeoutMs: config.dockerRecoveryStartupTimeoutMs,
+                canRecover: () => this.activeSessions.size === 0 && this.reservations.size === 0,
+            },
+            onStatus: logBridgeStatus,
+        });
+        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();
+            }
+        }
+        await this.dockerEngineProbe.refresh(true);
+        if (!this.hostCapabilitiesDetected) {
+            this.hostCapabilities = await this.hostCapabilityProbe.detect(this.config);
+            this.hostCapabilitiesDetected = true;
+        }
         const connection = this.connections.create(this.config);
         this.connection = connection;
+        this.transportRecovery = null;
         this.closed = new Promise((resolve) => {
-            connection.onClose(() => {
+            connection.onClose((error) => {
                 this.stopHeartbeat();
+                this.completeTransportRecovery(error ?? new Error("bridge connection closed"));
                 this.abortActiveSessions("bridge connection closed");
+                this.abortActiveReadinessProbes("bridge connection closed");
                 resolve();
             });
         });
+        connection.onReconnecting?.((error) => {
+            if (connection !== this.connection || this.stopped)
+                return;
+            this.stopHeartbeat();
+            this.beginTransportRecovery();
+            logBridgeStatus(`Forge connection interrupted${error ? `: ${errorMessage(error)}` : ""}. Reconnecting in place; active dispatches remain supervised...`);
+        });
+        connection.onReconnected?.(async () => {
+            if (connection !== this.connection || this.stopped)
+                return;
+            try {
+                await this.registerConnection(connection);
+                this.completeTransportRecovery();
+                this.startHeartbeat();
+                await this.flushCleanupReports().catch(() => undefined);
+                logBridgeStatus("Forge connection restored; active dispatches remain attached to this runner process.");
+            }
+            catch (error) {
+                this.completeTransportRecovery(error);
+                logBridgeStatus(`Forge reconnect registration failed: ${errorMessage(error)}. Closing the connection for a clean retry...`);
+                await connection.stop().catch(() => undefined);
+            }
+        });
         connection.onDispatch((dispatch) => this.handleDispatch(dispatch));
+        connection.onOffer?.((dispatch) => this.handleOffer(dispatch));
+        connection.onStart?.((dispatch) => this.handleStart(dispatch));
+        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,
-            protocolVersion: this.config.protocolVersion,
-            minServerVersion: this.config.minServerVersion ?? null,
-            capabilities: this.capabilities()
-        });
+        await this.registerConnection(connection);
+        await this.flushCleanupReports();
         this.startHeartbeat();
+        this.startLeaseWatchdog();
+        this.startSandboxMaintenance();
+    }
+    async registerConnection(connection) {
+        let storageRecoveryAttempt = 0;
+        while (true) {
+            try {
+                const ack = await connection.invoke("Hello", {
+                    version: this.config.version,
+                    protocolVersion: this.config.protocolVersion,
+                    minServerVersion: this.config.minServerVersion ?? null,
+                    runnerInstanceId: this.config.runnerInstanceId,
+                    capabilities: this.capabilities()
+                });
+                if (!ack.accepted) {
+                    throw new BridgeCallbackRejectedError(ack.code ?? null, ack.message ?? ack.code ?? "Hello callback was rejected.");
+                }
+                return;
+            }
+            catch (error) {
+                if (!isProviderStorageUnavailable(error) || storageRecoveryAttempt >= this.config.reconnectBackoffMs.length) {
+                    throw error;
+                }
+                const backoff = this.config.reconnectBackoffMs[storageRecoveryAttempt] ?? 5000;
+                storageRecoveryAttempt += 1;
+                logBridgeStatus(`Hello reached Forge while storage was recovering. Retrying registration ${storageRecoveryAttempt} in ${formatDelay(backoff)}...`);
+                await delay(backoff);
+            }
+        }
     }
     async run(signal) {
         let attempt = 0;
@@ -72,6 +228,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();
         }
@@ -79,31 +236,75 @@ export class ForgeBridgeService {
     async stop() {
         this.stopped = true;
         this.abortActiveSessions("bridge stopping");
+        this.abortActiveReadinessProbes("bridge stopping");
         await this.stopConnection();
+        await this.preflight.release();
     }
     async handleDispatch(rawDispatch) {
         const dispatch = this.parseDispatchOrReport(rawDispatch);
         if (!dispatch) {
             return;
         }
+        const capabilityFailure = await this.requiredCapabilityFailure(dispatch);
+        if (capabilityFailure) {
+            await this.sendResult(dispatch, failureResult(capabilityFailure, [{
+                    role: "runner",
+                    kind: "error",
+                    content: capabilityFailure,
+                    eventType: "docker_engine_unavailable",
+                }])).catch(() => undefined);
+            return;
+        }
         const leaseId = dispatch.lease.id;
         const fencingToken = dispatch.lease.fencingToken;
         const redactionSecrets = exactSecrets(dispatch, this.config);
-        if (this.activeSessions.has(leaseId)) {
-            await this.sendResult(leaseId, fencingToken, failureResult("Dispatch is already active on this bridge.")).catch(() => undefined);
+        const existing = this.activeSessions.get(leaseId);
+        if (existing) {
+            if (existing.fencingToken === fencingToken) {
+                return;
+            }
+            await this.sendResult(dispatch, failureResult("Dispatch fence conflicts with an active bridge session.")).catch(() => undefined);
             return;
         }
         const controller = new AbortController();
-        this.activeSessions.set(leaseId, { fencingToken, controller });
+        this.activeSessions.set(leaseId, {
+            fencingToken,
+            dispatchAttemptId: dispatch.sandbox?.dispatchAttemptId ?? null,
+            runnerInstanceId: dispatch.sandbox?.runnerInstanceId ?? null,
+            leaseExpiresAt: dispatch.lease.expiresAt,
+            sandboxed: dispatch.sandbox?.executionMode === "docker",
+            resources: dispatch.sandbox?.executionMode === "docker"
+                ? dispatch.sandbox.requestedResources
+                : zeroSandboxResources(),
+            controller
+        });
         try {
             const normalized = this.normalizeDispatch(dispatch);
-            const result = await this.sessions.runOnce(normalized, {
+            if (normalized.sandbox) {
+                const started = {
+                    dispatchAttemptId: normalized.sandbox.dispatchAttemptId,
+                    leaseId,
+                    fencingToken,
+                    runnerInstanceId: normalized.sandbox.runnerInstanceId
+                };
+                await this.invokeAck("DispatchStarted", started);
+            }
+            const sink = {
                 emit: async (event) => {
+                    if (event.eventType === "provider_cli_started") {
+                        const active = this.activeSessions.get(leaseId);
+                        if (active)
+                            active.resources = { ...active.resources, buildSlots: 0 };
+                    }
                     try {
                         await this.invokeAck("DispatchEvent", {
                             leaseId,
                             fencingToken,
-                            event: redactSecrets(event, redactionSecrets)
+                            ...(dispatch.sandbox ? {
+                                dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
+                                runnerInstanceId: dispatch.sandbox.runnerInstanceId
+                            } : {}),
+                            event: redactRunnerDispatchEvent(event, redactionSecrets)
                         });
                     }
                     catch (error) {
@@ -114,18 +315,302 @@ export class ForgeBridgeService {
                         throw error;
                     }
                 }
-            }, controller.signal);
-            await this.sendResult(leaseId, fencingToken, redactSecrets(result, redactionSecrets));
+            };
+            const result = normalized.sandbox?.executionMode === "docker"
+                ? await this.sandboxRuntime.runOnce(normalized, sink, controller.signal)
+                : await this.sessions.runOnce(normalized, sink, controller.signal);
+            if (normalized.sandbox?.executionMode === "docker") {
+                await this.flushCleanupReports().catch(() => undefined);
+            }
+            const redactedResult = redactRunOnceResultPacket(result, redactionSecrets);
+            await this.releaseActiveSessionAndRefreshCapacity(leaseId);
+            await this.sendResult(dispatch, compactTerminalResult(dispatch, redactedResult));
         }
         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(leaseId, fencingToken, failureResult(summary)).catch(() => undefined);
+            const failureEventType = infrastructureFailureEventType(summary);
+            const failureEvents = failureEventType ? [{
+                    role: "runner",
+                    kind: "error",
+                    content: summary,
+                    eventType: failureEventType,
+                }] : [];
+            await this.releaseActiveSessionAndRefreshCapacity(leaseId);
+            await this.sendResult(dispatch, failureResult(summary, failureEvents)).catch(() => undefined);
         }
         finally {
-            this.activeSessions.delete(leaseId);
+            await this.releaseActiveSessionAndRefreshCapacity(leaseId);
+        }
+    }
+    async releaseActiveSessionAndRefreshCapacity(leaseId) {
+        if (!this.activeSessions.delete(leaseId))
+            return;
+        // Publish released host/runtime capacity before the terminal result can
+        // enqueue the next pipeline phase. Otherwise the server may reject that
+        // handoff from the previous periodic heartbeat's active reservation.
+        await this.sendHeartbeat().catch(() => undefined);
+    }
+    async handleOffer(rawDispatch) {
+        const envelope = parseOfferEnvelope(rawDispatch);
+        if (!envelope) {
+            return;
+        }
+        const dispatch = this.parseDispatchOrReport(envelope.dispatch);
+        if (!dispatch?.sandbox
+            || dispatch.sandbox.dispatchAttemptId !== envelope.dispatchAttemptId
+            || dispatch.lease.id !== envelope.leaseId
+            || dispatch.lease.fencingToken !== envelope.fencingToken)
+            return;
+        const sandbox = dispatch.sandbox;
+        this.expireReservations(Date.now());
+        const existing = this.reservations.get(sandbox.dispatchAttemptId);
+        if (existing) {
+            const sameFence = existing.leaseId === dispatch.lease.id
+                && existing.fencingToken === dispatch.lease.fencingToken
+                && existing.runnerInstanceId === sandbox.runnerInstanceId;
+            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) {
+            await this.sendOfferDecision(dispatch, false, "stale_runner_instance", "Offer targets a different runner process instance.");
+            return;
+        }
+        if (Date.parse(envelope.expiresAt) <= Date.now()) {
+            await this.sendOfferDecision(dispatch, false, "lease_expired", "Offer lease is already expired.");
+            return;
+        }
+        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, 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_policy_denied", providerNetworkFailure);
+                return;
+            }
+            const authFailure = sandboxAuthFailure(dispatch, this.config);
+            if (authFailure) {
+                await this.sendOfferDecision(dispatch, false, "sandbox_auth_unavailable", authFailure);
+                return;
+            }
         }
+        let requestedResources = sandbox.requestedResources;
+        let sandboxConfigCommitSha = sandbox.sandboxConfigCommitSha ?? null;
+        const normalizedDispatch = this.normalizeDispatch(dispatch);
+        if (sandbox.executionMode === "docker") {
+            try {
+                const profile = await this.sandboxResourceResolver(normalizedDispatch);
+                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;
+            }
+        }
+        else if (normalizedDispatch.repo.serverLocalPath) {
+            // Host execution uses the same project-derived disk reservation as Docker.
+            // The API supplies a placement-time estimate; the runner can safely raise it
+            // from its authoritative checkout before admitting the attempt.
+            const measuredWorkspaceBytes = await estimateWorkspaceBytesFromRepo(normalizedDispatch.repo.serverLocalPath, { role: normalizedDispatch.execution.role }).catch(() => null);
+            if (measuredWorkspaceBytes !== null) {
+                requestedResources = {
+                    ...requestedResources,
+                    workspaceBytes: Math.max(requestedResources.workspaceBytes, measuredWorkspaceBytes),
+                };
+            }
+        }
+        // Resource profiling can await filesystem and Docker work. Admission needs
+        // a dynamic host/daemon sample that began after profiling completed, so an
+        // older in-flight heartbeat inspection cannot supply the commit decision.
+        const admissionPreflight = sandbox.executionMode === "docker"
+            ? await this.preflight.refreshCapacityForAdmission()
+            : preflight;
+        // Resource profiling and preflight may await slow filesystem or Docker I/O.
+        // Re-read every mutable capacity input only after that work, then decide and
+        // commit synchronously. JavaScript cannot interleave another Offer handler
+        // inside this non-async method, so the ledger check and insertion are one
+        // atomic event-loop turn without holding a lock across external I/O.
+        const decision = this.commitOfferReservation(dispatch, requestedResources, admissionPreflight);
+        await this.sendOfferDecision(dispatch, decision.accepted, decision.code, decision.message, decision.reservedUntil, decision.resources, sandboxConfigCommitSha);
+    }
+    commitOfferReservation(dispatch, requestedResources, preparedPreflight) {
+        const sandbox = dispatch.sandbox;
+        const now = Date.now();
+        this.expireReservations(now);
+        const existing = this.reservations.get(sandbox.dispatchAttemptId);
+        if (existing) {
+            const sameFence = existing.leaseId === dispatch.lease.id
+                && existing.fencingToken === dispatch.lease.fencingToken
+                && existing.runnerInstanceId === sandbox.runnerInstanceId;
+            return {
+                accepted: sameFence,
+                code: sameFence ? null : "stale_fence",
+                message: sameFence ? null : "Offer fence conflicts with the existing reservation.",
+                reservedUntil: sameFence ? existing.reservedUntil : null,
+                resources: sameFence ? existing.resources : null,
+            };
+        }
+        if (Date.parse(dispatch.lease.expiresAt) <= now) {
+            return rejectedOfferReservation("lease_expired", "Offer lease is already expired.");
+        }
+        if (sandbox.executionMode === "docker") {
+            // A concurrent heartbeat/preflight refresh may have produced a newer
+            // conservative dual-domain sample while this offer was being profiled.
+            const admissionPreflight = this.preflight.current() ?? preparedPreflight;
+            if (!this.config.dockerEnabled || !admissionPreflight?.healthy) {
+                return rejectedOfferReservation(admissionPreflight?.unavailableCode ?? "docker_unavailable", admissionPreflight?.unavailableReason ?? "Docker sandbox preflight is unavailable.");
+            }
+            const runtimeState = this.sandboxRuntime.snapshot();
+            const usedResources = this.usedSandboxResources(runtimeState.degraded);
+            const activeResources = this.activeSandboxResources(runtimeState.degraded);
+            const capacity = this.sandboxResourceCapacity(admissionPreflight, activeResources, usedResources);
+            if (!canReserveSandboxResources(usedResources, requestedResources, capacity)) {
+                return rejectedOfferReservation("capacity_unavailable", sandboxCapacityFailureMessage(usedResources, requestedResources, capacity, admissionPreflight, this.config));
+            }
+        }
+        const reservedUntil = new Date(Math.min(Date.parse(dispatch.lease.expiresAt), now + 30_000)).toISOString();
+        const reservation = {
+            leaseId: dispatch.lease.id,
+            fencingToken: dispatch.lease.fencingToken,
+            runnerInstanceId: sandbox.runnerInstanceId,
+            expiresAt: dispatch.lease.expiresAt,
+            reservedUntil,
+            sandboxed: sandbox.executionMode === "docker",
+            resources: requestedResources,
+        };
+        this.reservations.set(sandbox.dispatchAttemptId, reservation);
+        return {
+            accepted: true,
+            code: null,
+            message: null,
+            reservedUntil,
+            resources: requestedResources,
+        };
+    }
+    async handleStart(rawDispatch) {
+        const envelope = parseStartEnvelope(rawDispatch);
+        if (!envelope) {
+            return;
+        }
+        let dispatch = this.parseDispatchOrReport(envelope.dispatch);
+        if (!dispatch?.sandbox
+            || dispatch.sandbox.dispatchAttemptId !== envelope.dispatchAttemptId
+            || dispatch.lease.id !== envelope.leaseId
+            || dispatch.lease.fencingToken !== envelope.fencingToken)
+            return;
+        const reservation = this.reservations.get(dispatch.sandbox.dispatchAttemptId);
+        if (!reservation
+            || reservation.leaseId !== dispatch.lease.id
+            || reservation.fencingToken !== dispatch.lease.fencingToken
+            || reservation.runnerInstanceId !== dispatch.sandbox.runnerInstanceId
+            || Date.parse(reservation.reservedUntil) <= Date.now()) {
+            await this.sendResult(dispatch, failureResult("Start rejected because its reservation is missing or stale.")).catch(() => undefined);
+            return;
+        }
+        if (dispatch.apiKeySecretGrant) {
+            this.reservations.delete(dispatch.sandbox.dispatchAttemptId);
+            await this.sendResult(dispatch, failureResult("Start rejected because protocol-v2 packets may not contain a plaintext provider grant.")).catch(() => undefined);
+            return;
+        }
+        if (dispatch.apiKeySecretGrantHandle) {
+            const response = await this.redeemSecretGrant(dispatch);
+            const grant = response.grant;
+            if (!response.accepted
+                || !grant
+                || grant.grantId !== dispatch.apiKeySecretGrantHandle.grantId
+                || grant.provider !== dispatch.apiKeySecretGrantHandle.provider
+                || Date.parse(grant.expiresAt) <= Date.now()) {
+                this.reservations.delete(dispatch.sandbox.dispatchAttemptId);
+                await this.sendResult(dispatch, failureResult(response.message ?? "Secret grant redemption was rejected.")).catch(() => undefined);
+                return;
+            }
+            dispatch = { ...dispatch, apiKeySecretGrant: grant, apiKeySecretGrantHandle: null };
+        }
+        else if (dispatch.execution.requiresApiKeySecretGrant) {
+            this.reservations.delete(dispatch.sandbox.dispatchAttemptId);
+            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);
+    }
+    async redeemSecretGrant(dispatch) {
+        const sandbox = dispatch.sandbox;
+        const handle = dispatch.apiKeySecretGrantHandle;
+        const connection = this.connection;
+        if (!connection)
+            return { accepted: false, code: "bridge.disconnected", message: "Bridge is disconnected.", grant: null };
+        return await connection.invoke("RedeemSecretGrant", {
+            dispatchAttemptId: sandbox.dispatchAttemptId,
+            leaseId: dispatch.lease.id,
+            fencingToken: dispatch.lease.fencingToken,
+            runnerInstanceId: sandbox.runnerInstanceId,
+            grantId: handle.grantId
+        });
+    }
+    async redeemPublishGrant(request, signal) {
+        if (signal?.aborted)
+            throw new Error(String(signal.reason ?? "publication cancelled"));
+        const connection = this.connection;
+        if (!connection)
+            throw new Error("sandbox_output_publish_forbidden: bridge is disconnected.");
+        const response = await connection.invoke("RedeemPublishGrant", request);
+        if (!response.accepted || !response.credential) {
+            throw new Error(`sandbox_output_publish_forbidden: ${response.message ?? response.code ?? "publication grant redemption was rejected"}`);
+        }
+        return response.credential;
+    }
+    async handleLeaseUpdate(request) {
+        if (request.runnerInstanceId !== this.config.runnerInstanceId) {
+            return;
+        }
+        const reservation = this.reservations.get(request.dispatchAttemptId);
+        if (reservation && reservation.leaseId === request.leaseId && reservation.fencingToken === request.fencingToken) {
+            reservation.expiresAt = request.expiresAt;
+        }
+        const active = this.activeSessions.get(request.leaseId);
+        if (active && active.fencingToken === request.fencingToken && active.dispatchAttemptId === request.dispatchAttemptId) {
+            active.leaseExpiresAt = 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, reservedResources = null, sandboxConfigCommitSha = null) {
+        if (!dispatch.sandbox)
+            return;
+        const payload = {
+            dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
+            leaseId: dispatch.lease.id,
+            fencingToken: dispatch.lease.fencingToken,
+            runnerInstanceId: dispatch.sandbox.runnerInstanceId,
+            accepted,
+            code,
+            message,
+            reservedUntil: accepted ? reservedUntil ?? dispatch.lease.expiresAt : null,
+            reservedResources: accepted ? reservedResources : null,
+            sandboxConfigCommitSha: accepted ? sandboxConfigCommitSha : null,
+        };
+        await this.invokeAck("OfferDecision", payload);
     }
     parseDispatchOrReport(rawDispatch) {
         try {
@@ -137,7 +622,7 @@ export class ForgeBridgeService {
                 return null;
             }
             const summary = invalidDispatchSummary(error);
-            void this.sendResult(identifiers.leaseId, identifiers.fencingToken, failureResult(summary, [
+            void this.sendLegacyResult(identifiers.leaseId, identifiers.fencingToken, failureResult(summary, [
                 {
                     role: "runner",
                     kind: "error",
@@ -155,12 +640,74 @@ export class ForgeBridgeService {
         }
         active.controller.abort(request.reason ?? "cancelled by server");
     }
+    async handleReap(request) {
+        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();
@@ -185,12 +732,20 @@ export class ForgeBridgeService {
                 : dispatch.qaBrowser
         };
     }
-    async sendResult(leaseId, fencingToken, result) {
+    async sendResult(dispatch, result) {
         const payload = {
-            leaseId,
-            fencingToken,
+            leaseId: dispatch.lease.id,
+            fencingToken: dispatch.lease.fencingToken,
+            dispatchAttemptId: dispatch.sandbox?.dispatchAttemptId ?? null,
+            runnerInstanceId: dispatch.sandbox?.runnerInstanceId ?? null,
             result
         };
+        await this.sendResultPayload(payload);
+    }
+    async sendLegacyResult(leaseId, fencingToken, result) {
+        await this.sendResultPayload({ leaseId, fencingToken, result });
+    }
+    async sendResultPayload(payload) {
         try {
             await this.invokeAck("DispatchResult", payload);
         }
@@ -203,19 +758,142 @@ 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);
+        this.leaseWatchdogTimer.unref?.();
+    }
+    stopLeaseWatchdog() {
+        if (this.leaseWatchdogTimer) {
+            clearInterval(this.leaseWatchdogTimer);
+            this.leaseWatchdogTimer = null;
+        }
+    }
+    expireLeases() {
+        const now = Date.now();
+        this.expireReservations(now);
+        for (const active of this.activeSessions.values()) {
+            if (Date.parse(active.leaseExpiresAt) <= now && !active.controller.signal.aborted) {
+                active.controller.abort("dispatch lease expired");
+            }
+        }
+    }
+    expireReservations(now) {
+        for (const [attemptId, reservation] of this.reservations) {
+            if (Date.parse(reservation.expiresAt) <= now || Date.parse(reservation.reservedUntil) <= now) {
+                this.reservations.delete(attemptId);
+            }
+        }
+    }
     stopHeartbeat() {
         if (this.heartbeatTimer) {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
     }
+    startSandboxMaintenance() {
+        this.stopSandboxMaintenance();
+        this.sandboxMaintenanceTimer = setInterval(() => {
+            this.runSandboxMaintenance().catch(() => undefined);
+        }, 60_000);
+        this.sandboxMaintenanceTimer.unref?.();
+    }
+    stopSandboxMaintenance() {
+        if (this.sandboxMaintenanceTimer) {
+            clearInterval(this.sandboxMaintenanceTimer);
+            this.sandboxMaintenanceTimer = null;
+        }
+    }
+    async runSandboxMaintenance() {
+        if (this.sandboxMaintenanceRunning)
+            return;
+        this.sandboxMaintenanceRunning = true;
+        try {
+            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 {
+            this.sandboxMaintenanceRunning = false;
+        }
+    }
+    async readAttemptSnapshot() {
+        const connection = this.connection;
+        if (!connection)
+            throw new Error("Bridge is not connected.");
+        const response = await connection.invoke("AttemptSnapshot", {
+            runnerInstanceId: this.config.runnerInstanceId
+        });
+        if (!response.accepted) {
+            throw new BridgeCallbackRejectedError(response.code ?? null, response.message ?? response.code ?? "Attempt snapshot was rejected.");
+        }
+        return response.attempts ?? [];
+    }
+    async flushCleanupReports() {
+        if (!this.sandboxRuntime.pendingCleanupReports || !this.sandboxRuntime.acknowledgeCleanupReport)
+            return;
+        for (const report of await this.sandboxRuntime.pendingCleanupReports()) {
+            await this.invokeAck("CleanupReport", {
+                runnerInstanceId: this.config.runnerInstanceId,
+                report
+            });
+            await this.sandboxRuntime.acknowledgeCleanupReport(report.reportId);
+        }
+    }
     async sendHeartbeat() {
+        // Heartbeats are the recovery path for capacity-blocked work. Refresh the
+        // dynamic sample before advertising it, while reusing the static Docker
+        // capability snapshot established at startup or by an offer.
+        if (this.config.dockerEnabled)
+            await this.preflight.refreshCapacity();
+        await this.dockerEngineProbe.refresh();
         await this.invokeAck("Heartbeat", {
             status: "online",
             capabilities: this.capabilities(),
@@ -224,8 +902,26 @@ export class ForgeBridgeService {
         });
     }
     capabilities() {
+        const preflight = this.preflight.current();
+        const dockerEngine = this.dockerEngineProbe.current();
+        const runtimeState = this.sandboxRuntime.snapshot();
+        const reserved = [...this.reservations.values()].filter(reservation => reservation.sandboxed).length;
+        const used = this.usedSandboxResources(runtimeState.degraded);
+        const activeResources = this.activeSandboxResources(runtimeState.degraded);
+        const capacity = this.sandboxResourceCapacity(preflight, activeResources, used);
+        const ambientMemoryCommitmentBytes = this.sandboxAmbientMemoryCommitmentBytes ?? 0;
+        const memoryAdmission = preflight ? buildMemoryAdmissionDiagnostics({
+            sampledAt: preflight.sampledAt,
+            totalMemoryBytes: preflight.totalMemoryBytes,
+            rawAvailableMemoryBytes: preflight.rawAvailableMemoryBytes,
+            stabilizedAvailableMemoryBytes: preflight.availableMemoryBytes,
+            controlPlaneMemoryBytes: process.memoryUsage().rss,
+            reserveMemoryBytes: preflight.hostReserveBytes,
+            committedMemoryBytes: ambientMemoryCommitmentBytes + used.memoryBytes,
+            pendingCommitmentMemoryBytes: Math.max(0, used.memoryBytes - activeResources.memoryBytes),
+        }) : null;
         return {
-            schemaVersion: 2,
+            schemaVersion: 5,
             activeSessionCount: this.activeSessions.size,
             cliProviders: this.config.cliProviders,
             providerStatuses: this.config.providerStatuses,
@@ -233,32 +929,199 @@ export class ForgeBridgeService {
             repoMappings: repoMappingsFor(this.config),
             os: this.config.os,
             sandboxProfiles: this.config.sandboxProfiles,
+            runnerInstanceId: this.config.runnerInstanceId,
+            trustDomainId: this.config.trustDomainId,
+            executionFacilities: dockerEngine?.available ? ["docker_engine"] : [],
+            dockerEngine,
+            toolchains: {
+                ...this.hostCapabilities.toolchains,
+                docker: {
+                    available: dockerEngine?.available === true,
+                    executable: this.config.dockerExecutable,
+                    version: dockerEngine?.runtimeVersion ?? null,
+                },
+            },
+            playwrightProjects: this.hostCapabilities.playwrightProjects,
+            browserLaunch: this.hostCapabilities.browserLaunch,
+            providerConnectivity: this.hostCapabilities.providerConnectivity,
+            maxConcurrentSandboxes: capacity.sandboxSlots,
+            reservedSandboxCount: reserved,
+            activeSandboxCount: runtimeState.active,
+            startingSandboxCount: runtimeState.starting,
+            degradedReservationCount: runtimeState.degraded,
+            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: memoryAdmission?.availableForAdmissionBytes ?? null,
+            availableCpuMillis: preflight ? Math.max(0, capacity.cpuMillis - used.cpuMillis) : null,
+            availableWorkspaceBytes: preflight ? Math.max(0, capacity.workspaceBytes - used.workspaceBytes) : null,
+            diskLow: preflight?.diskLow ?? null,
+            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.rawDaemonAvailableMemoryBytes ?? 0,
+                hostAvailableBytes: preflight.rawHostAvailableMemoryBytes,
+                conservativeAvailableBytes: preflight.rawAvailableMemoryBytes,
+                availableForAdmissionBytes: memoryAdmission.availableForAdmissionBytes,
+                memoryAdmission: memoryAdmission,
+            } : null,
+            hostRuntime: this.sessions.runtimeCapacity?.() ?? null,
             supportsApiSecretGrant: this.config.supportsApiSecretGrant,
             supportsManagedWorktrees: this.config.supportsManagedWorktrees,
             supportsManagedForgeArtifacts: this.config.supportsManagedForgeArtifacts,
             supportsRunnerAuthoredPhaseArtifacts: this.config.supportsRunnerAuthoredPhaseArtifacts,
-            supportsDraftRunOnce: this.config.supportsDraftRunOnce
+            supportsDraftRunOnce: this.config.supportsDraftRunOnce,
+            supportsDraftAttachments: this.config.supportsDraftAttachments,
+            supportsDraftImageAttachments: this.config.supportsDraftImageAttachments
+        };
+    }
+    async requiredCapabilityFailure(dispatch) {
+        const requiredCapabilities = dispatch.qaScope?.required_capabilities ?? [];
+        if (!requiredCapabilities.includes("docker_engine"))
+            return null;
+        const executionMode = dispatch.sandbox?.executionMode;
+        if (executionMode === "docker") {
+            return dockerEngineRequirementFailure(requiredCapabilities, executionMode, null);
+        }
+        return dockerEngineRequirementFailure(requiredCapabilities, executionMode, await this.dockerEngineProbe.refresh(true));
+    }
+    usedSandboxResources(degradedReservations) {
+        const resources = [
+            ...[...this.reservations.values()]
+                .filter(reservation => reservation.sandboxed)
+                .map(reservation => reservation.resources),
+            ...[...this.activeSessions.values()]
+                .filter(session => session.sandboxed)
+                .map(session => session.resources),
+            ...Array.from({ length: degradedReservations }, () => defaultSandboxResources())
+        ];
+        return sumSandboxResources(resources);
+    }
+    activeSandboxResources(degradedReservations) {
+        return sumSandboxResources([
+            ...[...this.activeSessions.values()]
+                .filter(session => session.sandboxed)
+                .map(session => session.resources),
+            ...Array.from({ length: degradedReservations }, () => defaultSandboxResources())
+        ]);
+    }
+    sandboxResourceCapacity(preflight, activeResources, usedResources) {
+        if (!preflight)
+            return zeroSandboxResources();
+        if (usedResources.memoryBytes === 0 || this.sandboxAmbientMemoryCommitmentBytes === null) {
+            // Freeze non-Forge daemon use while reservations exist. If the bridge
+            // reconnects with managed containers already present, the initial value
+            // is deliberately conservative until their ledger drains.
+            this.sandboxAmbientMemoryCommitmentBytes = Math.max(0, preflight.totalMemoryBytes - preflight.rawAvailableMemoryBytes);
+        }
+        return {
+            // 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,
+            workerMemoryLimitBytes: 0,
+            serviceMemoryLimitBytes: 0,
+            runtimeOverheadBytes: 0,
+            memoryBytes: sandboxMemoryCommitmentCapacity(preflight, activeResources.memoryBytes, this.sandboxAmbientMemoryCommitmentBytes),
+            workspaceBytes: Math.max(0, preflight.availableWorkspaceBytes
+                - this.config.minimumWorkspaceBytes
+                + activeResources.workspaceBytes),
+            pids: this.config.sandboxPidCapacity,
+            buildSlots: this.config.maxConcurrentSandboxBuilds
         };
     }
     async invokeAck(methodName, payload) {
-        const connection = this.connection;
-        if (!connection) {
-            throw new Error("Bridge is not connected.");
+        let storageRecoveryAttempt = 0;
+        while (true) {
+            const connection = this.connection;
+            if (!connection) {
+                throw new Error("Bridge is not connected.");
+            }
+            await this.waitForTransportRecovery(connection, this.transportRecovery);
+            const recoveryGeneration = this.transportRecoveryGeneration;
+            try {
+                const ack = await waitForCallbackAck(connection.invoke(methodName, payload), methodName, positiveFiniteNumber(this.config.callbackAckTimeoutMs ?? 30_000, 30_000));
+                if (!ack.accepted) {
+                    throw new BridgeCallbackRejectedError(ack.code ?? null, ack.message ?? ack.code ?? `${methodName} callback was rejected.`);
+                }
+                return ack;
+            }
+            catch (error) {
+                if (connection !== this.connection || this.stopped)
+                    throw error;
+                const recovery = this.transportRecovery;
+                if (recovery && recovery.generation > recoveryGeneration) {
+                    await this.waitForTransportRecovery(connection, recovery);
+                    continue;
+                }
+                if (isProviderStorageUnavailable(error) && storageRecoveryAttempt < this.config.reconnectBackoffMs.length) {
+                    const backoff = this.config.reconnectBackoffMs[storageRecoveryAttempt] ?? 5000;
+                    storageRecoveryAttempt += 1;
+                    logBridgeStatus(`${methodName} reached Forge while storage was recovering. Retrying callback ${storageRecoveryAttempt} in ${formatDelay(backoff)}...`);
+                    await delay(backoff);
+                    continue;
+                }
+                throw error;
+            }
         }
-        const ack = await connection.invoke(methodName, payload);
-        if (!ack.accepted) {
-            throw new BridgeCallbackRejectedError(ack.code ?? null, ack.message ?? ack.code ?? `${methodName} callback was rejected.`);
+    }
+    beginTransportRecovery() {
+        if (this.transportRecovery && !this.transportRecovery.completed)
+            return;
+        let resolve = () => undefined;
+        const promise = new Promise((complete) => { resolve = complete; });
+        this.transportRecoveryGeneration += 1;
+        this.transportRecovery = {
+            generation: this.transportRecoveryGeneration,
+            promise,
+            resolve,
+            completed: false,
+            error: null,
+        };
+    }
+    completeTransportRecovery(error = null) {
+        const recovery = this.transportRecovery;
+        if (!recovery || recovery.completed)
+            return;
+        recovery.completed = true;
+        recovery.error = error;
+        recovery.resolve();
+    }
+    async waitForTransportRecovery(connection, recovery) {
+        if (!recovery)
+            return;
+        if (recovery.completed) {
+            if (recovery.error)
+                throw recovery.error;
+            return;
         }
-        return ack;
+        await recovery.promise;
+        if (connection !== this.connection)
+            throw new Error("Bridge connection changed while recovering.");
+        if (recovery.error)
+            throw recovery.error;
     }
     async waitForClose(signal) {
         if (!this.closed) {
             return;
         }
-        await Promise.race([this.closed, abortPromise(signal)]);
+        await waitForPromiseOrAbort(this.closed, signal);
     }
     async stopConnection() {
         this.stopHeartbeat();
+        this.stopLeaseWatchdog();
+        this.stopSandboxMaintenance();
         if (this.connection) {
             await this.connection.stop().catch(() => undefined);
             this.connection = null;
@@ -279,6 +1142,17 @@ function isDispatchNoLongerPending(error) {
     }
     return error instanceof Error && error.message === "Dispatch is no longer pending.";
 }
+function isProviderStorageUnavailable(error) {
+    const message = errorMessage(error).toLowerCase();
+    return message.includes("provider_storage_unavailable")
+        || (message.includes("storage is recovering") && message.includes("503"));
+}
+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);
@@ -301,8 +1175,12 @@ export class SignalRBridgeConnection {
                 Authorization: `Bearer ${config.deviceToken}`
             }
         })
+            .withAutomaticReconnect([...config.reconnectBackoffMs])
             .configureLogging(LogLevel.Warning)
             .build();
+        this.connection.on("Superseded", () => {
+            void this.connection.stop().catch(() => undefined);
+        });
     }
     start() {
         return this.connection.start();
@@ -313,16 +1191,49 @@ export class SignalRBridgeConnection {
     onClose(handler) {
         this.connection.onclose(handler);
     }
+    onReconnecting(handler) {
+        this.connection.onreconnecting(handler);
+    }
+    onReconnected(handler) {
+        this.connection.onreconnected((connectionId) => {
+            void Promise.resolve(handler(connectionId)).catch(() => undefined);
+        });
+    }
     onDispatch(handler) {
         this.connection.on("Dispatch", (raw) => {
             void handler(raw).catch(() => undefined);
         });
     }
+    onOffer(handler) {
+        this.connection.on("Offer", (raw) => {
+            void handler(raw).catch(() => undefined);
+        });
+    }
+    onStart(handler) {
+        this.connection.on("Start", (raw) => {
+            void handler(raw).catch(() => undefined);
+        });
+    }
+    onLeaseUpdate(handler) {
+        this.connection.on("LeaseUpdate", (request) => {
+            void handler(request).catch(() => undefined);
+        });
+    }
     onCancel(handler) {
         this.connection.on("Cancel", (request) => {
             void handler(request).catch(() => undefined);
         });
     }
+    onReap(handler) {
+        this.connection.on("Reap", (request) => {
+            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);
     }
@@ -330,9 +1241,41 @@ export class SignalRBridgeConnection {
 export function defaultBridgeServiceConfig(overrides = {}) {
     const defaults = defaultForgeBridgeConfig();
     const cliProviders = splitCsv(process.env.FORGE_CLI_PROVIDERS ?? "codex");
+    const configuredSandboxHostMemoryReserveBytes = optionalPositiveFiniteNumber(process.env.FORGE_SANDBOX_HOST_MEMORY_RESERVE_BYTES);
+    const sandboxPublicationMode = process.env.FORGE_SANDBOX_PUBLICATION_MODE === "bridge_push" ? "bridge_push" : "shared_filesystem";
     const config = {
         serverUrl: process.env.FORGE_URL ?? "http://localhost:5208",
         runnerId: process.env.FORGE_RUNNER_ID ?? "",
+        runnerInstanceId: process.env.FORGE_RUNNER_INSTANCE_ID ?? randomUUID(),
+        trustDomainId: process.env.FORGE_TRUST_DOMAIN_ID ?? "default",
+        maxConcurrentSandboxes: positiveFiniteNumber(Number(process.env.FORGE_MAX_CONCURRENT_SANDBOXES ?? 3), 3),
+        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 ?? "",
+        dockerDesktopRecoveryEnabled: process.env.FORGE_DOCKER_DESKTOP_AUTO_RECOVERY === "true",
+        dockerRecoveryFailureThreshold: positiveFiniteNumber(Number(process.env.FORGE_DOCKER_RECOVERY_FAILURE_THRESHOLD ?? 3), 3),
+        dockerRecoveryCooldownMs: positiveFiniteNumber(Number(process.env.FORGE_DOCKER_RECOVERY_COOLDOWN_MS ?? 10 * 60_000), 10 * 60_000),
+        dockerRecoveryStartupTimeoutMs: positiveFiniteNumber(Number(process.env.FORGE_DOCKER_RECOVERY_STARTUP_TIMEOUT_MS ?? 2 * 60_000), 2 * 60_000),
+        sandboxStateRoot: process.env.FORGE_SANDBOX_STATE_ROOT ?? path.join(os.homedir(), ".forge", "bridge", "sandboxes"),
+        requireRootlessDocker: process.env.FORGE_REQUIRE_ROOTLESS_DOCKER === "true" || process.platform === "linux",
+        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),
+        // Undefined means preflight derives the bounded reserve from the actual
+        // Docker/host capacity domain after sampling it.
+        sandboxHostMemoryReserveBytes: configuredSandboxHostMemoryReserveBytes,
+        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),
+        auditRetentionTtlMs: positiveFiniteNumber(Number(process.env.FORGE_SANDBOX_AUDIT_RETENTION_TTL_MS ?? 30 * 24 * 60 * 60 * 1000), 30 * 24 * 60 * 60 * 1000),
         deviceToken: process.env.FORGE_DEVICE_TOKEN ?? "",
         deviceName: process.env.FORGE_DEVICE_NAME ?? "",
         defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? defaults.defaultRepoRoot,
@@ -348,17 +1291,23 @@ export function defaultBridgeServiceConfig(overrides = {}) {
         supportsManagedForgeArtifacts: true,
         supportsRunnerAuthoredPhaseArtifacts: true,
         supportsDraftRunOnce: true,
+        supportsDraftAttachments: true,
+        supportsDraftImageAttachments: supportsDraftImageAttachmentsFor(cliProviders),
         version: process.env.FORGE_BRIDGE_VERSION ?? forgeBridgeVersion,
-        protocolVersion: 1,
+        protocolVersion: 2,
         minServerVersion: null,
         heartbeatIntervalMs: positiveFiniteNumber(Number(process.env.FORGE_HEARTBEAT_INTERVAL_MS ?? 30_000), 30_000),
+        callbackAckTimeoutMs: positiveFiniteNumber(Number(process.env.FORGE_CALLBACK_ACK_TIMEOUT_MS ?? 30_000), 30_000),
         reconnectBackoffMs: [1000, 2000, 5000, 10000, 30000],
         ...overrides
     };
     return {
         ...config,
+        providerStatuses: overrides.providerStatuses ?? providerStatusesFor(config.cliProviders),
         sandboxProfiles: config.sandboxProfiles ?? defaultSandboxProfiles(config.cliProviders),
-        heartbeatIntervalMs: positiveFiniteNumber(config.heartbeatIntervalMs, 30_000)
+        supportsDraftImageAttachments: (overrides.supportsDraftImageAttachments ?? true) && supportsDraftImageAttachmentsFor(config.cliProviders),
+        heartbeatIntervalMs: positiveFiniteNumber(config.heartbeatIntervalMs, 30_000),
+        callbackAckTimeoutMs: positiveFiniteNumber(config.callbackAckTimeoutMs ?? 30_000, 30_000),
     };
 }
 export function resolveBridgeRunnerHubUrl(serverUrl) {
@@ -373,9 +1322,42 @@ function normalizeServerUrl(serverUrl) {
 function positiveFiniteNumber(value, fallback) {
     return Number.isFinite(value) && value > 0 ? value : fallback;
 }
+function optionalPositiveFiniteNumber(value) {
+    if (value === undefined || value.trim().length === 0)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+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) }]));
 }
+function sandboxAuthModesFor(config) {
+    return Object.fromEntries(config.cliProviders.map((provider) => {
+        const modes = ["api_key"];
+        if (sandboxBridgeCliAuthAvailable(config, provider)) {
+            modes.push("bridge_cli");
+        }
+        return [provider, modes];
+    }));
+}
+function sandboxBridgeCliAuthAvailable(config, provider) {
+    if (provider.trim().toLowerCase() !== "codex") {
+        return false;
+    }
+    const status = providerStatus(config, provider);
+    if (status?.signedIn === false) {
+        return false;
+    }
+    return codexSandboxProviderAuthAdapter.doctor().available;
+}
+function providerStatus(config, provider) {
+    const normalized = provider.trim().toLowerCase();
+    return Object.entries(config.providerStatuses)
+        .find(([key]) => key.trim().toLowerCase() === normalized)?.[1];
+}
 function defaultSandboxProfiles(providers, platform = process.platform) {
     if (!providers.some((provider) => provider.toLowerCase() === "codex")) {
         return ["none"];
@@ -470,10 +1452,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;
 }
@@ -515,33 +1498,361 @@ function formatDelay(ms) {
     }
     return `${ms}ms`;
 }
+async function waitForCallbackAck(callback, methodName, timeoutMs) {
+    let timeout = null;
+    const expired = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            reject(new Error(`bridge_callback_timeout: ${methodName} callback was not acknowledged within ${formatDelay(timeoutMs)}.`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([callback, expired]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
 function logBridgeStatus(message) {
     process.stderr.write(`[${new Date().toISOString()}] ${message}\n`);
 }
-function delay(ms, signal) {
+export function delay(ms, signal) {
     if (signal?.aborted) {
         return Promise.resolve();
     }
     return new Promise((resolve) => {
-        const timeout = setTimeout(resolve, ms);
-        signal?.addEventListener("abort", () => {
+        const complete = () => {
             clearTimeout(timeout);
+            signal?.removeEventListener("abort", complete);
             resolve();
-        }, { once: true });
+        };
+        const timeout = setTimeout(complete, ms);
+        signal?.addEventListener("abort", complete, { once: true });
+        if (signal?.aborted)
+            complete();
     });
 }
-function abortPromise(signal) {
+export async function waitForPromiseOrAbort(promise, signal) {
     if (!signal) {
-        return new Promise(() => undefined);
+        await promise;
+        return;
     }
     if (signal.aborted) {
-        return Promise.resolve();
+        return;
+    }
+    let resolveAbort;
+    const abort = new Promise(resolve => { resolveAbort = resolve; });
+    signal.addEventListener("abort", resolveAbort, { once: true });
+    try {
+        await Promise.race([promise, abort]);
+    }
+    finally {
+        signal.removeEventListener("abort", resolveAbort);
+    }
+}
+export function canReapManagedSandboxes(preflight) {
+    return canRunDockerMaintenance(preflight);
+}
+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" || !config.allowOpenPublicSandbox)) {
+        return "open_public sandbox networking is not permitted by this runner policy.";
+    }
+    if (sandbox.networkPolicy.mode === "public_allowlist"
+        && sandbox.networkPolicy.allowedHosts.length > 0
+        && process.env.FORGE_SANDBOX_EGRESS_ENFORCED !== "true") {
+        return "public_allowlist requires an operator-enforced Forge egress proxy or firewall.";
+    }
+    return null;
+}
+export function infrastructureFailureEventType(summary) {
+    const sandboxFailure = /^(sandbox_[a-z0-9_.-]+|image_[a-z0-9_.-]+|contract_[a-z0-9_.-]+|teardown_[a-z0-9_.-]+):/u.exec(summary)?.[1];
+    if (sandboxFailure)
+        return sandboxFailure;
+    if (summary.startsWith("worktree_prepare_failed:"))
+        return "worktree_prepare_failed";
+    if (summary.startsWith("provider_network_unavailable:"))
+        return "provider_network_unavailable";
+    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("docker_engine_unavailable:"))
+        return "docker_engine_unavailable";
+    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";
+    if (summary.startsWith("bridge_callback_timeout:"))
+        return "bridge_callback_timeout";
+    return null;
+}
+export function dockerEngineRequirementFailure(requiredCapabilities, executionMode, capability) {
+    if (!requiredCapabilities.includes("docker_engine"))
+        return null;
+    if (executionMode === "docker") {
+        return "docker_engine_unavailable: docker_engine is not exposed inside Forge agent sandboxes; use a managed host runner with Docker-daemon access.";
+    }
+    return capability?.available
+        ? null
+        : `docker_engine_unavailable: ${capability?.unavailableReason ?? "Docker daemon is unreachable from the bridge process."}`;
+}
+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 new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+    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) {
+        return unsupported;
+    }
+    if (dispatch.execution.authKind.trim().toLowerCase() !== "bridge_cli") {
+        return null;
+    }
+    const status = providerStatus(config, dispatch.execution.provider);
+    if (status?.signedIn === false) {
+        return `${dispatch.execution.provider} Local CLI is not signed in on this runner.`;
+    }
+    const adapter = sandboxProviderAuthAdapterFor(dispatch.execution.provider, dispatch.execution.authKind);
+    if (!adapter) {
+        return `${dispatch.execution.provider} Local CLI auth is not portable into Docker yet.`;
+    }
+    const doctor = adapter.doctor();
+    return doctor.available ? null : doctor.message;
+}
+function rejectedOfferReservation(code, message) {
+    return {
+        accepted: false,
+        code,
+        message,
+        reservedUntil: null,
+        resources: null,
+    };
+}
+export function canReserveSandboxResources(used, requested, capacity) {
+    return used.sandboxSlots + requested.sandboxSlots <= capacity.sandboxSlots
+        && used.cpuMillis + requested.cpuMillis <= capacity.cpuMillis
+        && used.memoryBytes + requested.memoryBytes <= capacity.memoryBytes
+        && used.workspaceBytes + requested.workspaceBytes <= capacity.workspaceBytes
+        && used.pids + requested.pids <= capacity.pids
+        && used.buildSlots + requested.buildSlots <= capacity.buildSlots;
 }
+export function sandboxMemoryCommitmentCapacity(preflight, activeMemoryBytes, ambientMemoryCommitmentBytes = 0) {
+    const ambientCapacity = preflight.availableMemoryBytes
+        - preflight.hostReserveBytes
+        + activeMemoryBytes;
+    const commitmentCapacity = preflight.totalMemoryBytes
+        - preflight.hostReserveBytes
+        - Math.max(0, ambientMemoryCommitmentBytes);
+    return Math.max(0, Math.min(ambientCapacity, commitmentCapacity));
+}
+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 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,
+        buildSlots: total.buildSlots + resource.buildSlots
+    }), zeroSandboxResources());
+}
+function zeroSandboxResources() {
+    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,
+        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);
+    const workspaceBytes = await estimateWorkspaceBytesFromRepo(repoPath, {
+        role: dispatch.execution.role,
+        serviceCount: contract.contract.services.length,
+        browser: contract.contract.browser,
+    });
+    return {
+        resources: resolveDynamicSandboxResources({
+            ...sandbox.requestedResources,
+            workspaceBytes: Math.max(sandbox.requestedResources.workspaceBytes, workspaceBytes),
+        }, 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);
+}
+function parseStartEnvelope(value) {
+    return parseDispatchEnvelope(value);
+}
+function parseDispatchEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const envelope = value;
+    if (envelope.schemaVersion !== 1
+        || typeof envelope.dispatchAttemptId !== "string"
+        || typeof envelope.leaseId !== "string"
+        || typeof envelope.fencingToken !== "string"
+        || typeof envelope.runnerInstanceId !== "string"
+        || typeof envelope.expiresAt !== "string"
+        || !envelope.dispatch)
+        return null;
+    return {
+        dispatchAttemptId: envelope.dispatchAttemptId,
+        leaseId: envelope.leaseId,
+        fencingToken: envelope.fencingToken,
+        runnerInstanceId: envelope.runnerInstanceId,
+        expiresAt: envelope.expiresAt,
+        dispatch: envelope.dispatch
+    };
+}
+const maxAttachmentExactSecretLength = 8 * 1024;
 function exactSecrets(dispatch, config) {
     return [
         dispatch.apiKeySecretGrant?.secret,
-        config.deviceToken
+        config.deviceToken,
+        ...boundedAttachmentExactSecrets(dispatch)
     ].filter((secret) => typeof secret === "string" && secret.length > 0);
 }
+function boundedAttachmentExactSecrets(dispatch) {
+    return (dispatch.draft?.attachments ?? [])
+        .flatMap((attachment) => [attachment.textContent, attachment.contentBase64])
+        .filter((secret) => typeof secret === "string" && secret.length > 0 && secret.length <= maxAttachmentExactSecretLength);
+}