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

package/dist/bridge/bridge.service.js

@@ -1,28 +1,58 @@
 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 { supportsDraftImageAttachmentsFor } from "../shared/provider-capabilities.js";
 import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
 import { BridgeSessionService } from "../session/session.service.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 { codexSandboxProviderAuthAdapter, sandboxProviderAuthAdapterFor, sandboxProviderAuthUnavailableMessage } from "../sandbox/provider-auth/codex.js";
 export class ForgeBridgeService {
     config;
     sessions;
     connections;
     connection = null;
     heartbeatTimer = null;
+    leaseWatchdogTimer = null;
+    sandboxMaintenanceTimer = null;
+    sandboxMaintenanceRunning = false;
     closed = null;
     stopped = false;
     activeSessions = new Map();
-    constructor(config, sessions = new BridgeSessionService(), connections = new SignalRBridgeConnectionFactory()) {
+    reservations = new Map();
+    preflight;
+    sandboxRuntime;
+    constructor(config, sessions = new BridgeSessionService(), connections = new SignalRBridgeConnectionFactory(), preflight, sandboxRuntime) {
         this.config = config;
         this.sessions = sessions;
         this.connections = connections;
+        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,
+            requireRootless: config.requireRootlessDocker
+        });
+        this.sandboxRuntime = sandboxRuntime ?? new DockerSandboxRuntime(config, (request, signal) => this.redeemPublishGrant(request, signal));
     }
     async connectOnce() {
         await this.stopConnection();
         this.stopped = false;
+        if (this.config.dockerEnabled) {
+            const preflight = await this.preflight.refresh();
+            if (canReapManagedSandboxes(preflight)) {
+                await this.sandboxRuntime.reap({ diskLow: preflight.diskLow });
+            }
+        }
         const connection = this.connections.create(this.config);
         this.connection = connection;
         this.closed = new Promise((resolve) => {
@@ -33,15 +63,23 @@ export class ForgeBridgeService {
             });
         });
         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));
         await connection.start();
         await this.invokeAck("Hello", {
             version: this.config.version,
             protocolVersion: this.config.protocolVersion,
             minServerVersion: this.config.minServerVersion ?? null,
+            runnerInstanceId: this.config.runnerInstanceId,
             capabilities: this.capabilities()
         });
+        await this.flushCleanupReports();
         this.startHeartbeat();
+        this.startLeaseWatchdog();
+        this.startSandboxMaintenance();
     }
     async run(signal) {
         let attempt = 0;
@@ -80,6 +118,7 @@ export class ForgeBridgeService {
         this.stopped = true;
         this.abortActiveSessions("bridge stopping");
         await this.stopConnection();
+        await this.preflight.release();
     }
     async handleDispatch(rawDispatch) {
         const dispatch = this.parseDispatchOrReport(rawDispatch);
@@ -89,20 +128,52 @@ export class ForgeBridgeService {
         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,
+                            ...(dispatch.sandbox ? {
+                                dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
+                                runnerInstanceId: dispatch.sandbox.runnerInstanceId
+                            } : {}),
                             event: redactSecrets(event, redactionSecrets)
                         });
                     }
@@ -114,19 +185,194 @@ 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);
+            }
+            await this.sendResult(dispatch, redactSecrets(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(leaseId, fencingToken, failureResult(summary)).catch(() => undefined);
+            await this.sendResult(dispatch, failureResult(summary)).catch(() => undefined);
         }
         finally {
             this.activeSessions.delete(leaseId);
         }
     }
+    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;
+        let existing = this.reservations.get(sandbox.dispatchAttemptId);
+        if (existing && Date.parse(existing.reservedUntil) <= Date.now()) {
+            this.reservations.delete(sandbox.dispatchAttemptId);
+            existing = undefined;
+        }
+        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);
+            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 = 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);
+            if (networkFailure) {
+                await this.sendOfferDecision(dispatch, false, "policy_mismatch", networkFailure);
+                return;
+            }
+            const authFailure = sandboxAuthFailure(dispatch, this.config);
+            if (authFailure) {
+                await this.sendOfferDecision(dispatch, false, "sandbox_auth_unavailable", authFailure);
+                return;
+            }
+        }
+        const runtimeState = this.sandboxRuntime.snapshot();
+        const usedResources = this.usedSandboxResources(runtimeState.degraded);
+        const capacity = this.sandboxResourceCapacity(preflight);
+        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.");
+            return;
+        }
+        const reservedUntil = new Date(Math.min(Date.parse(dispatch.lease.expiresAt), Date.now() + 30_000)).toISOString();
+        this.reservations.set(sandbox.dispatchAttemptId, {
+            leaseId: dispatch.lease.id,
+            fencingToken: dispatch.lease.fencingToken,
+            runnerInstanceId: sandbox.runnerInstanceId,
+            expiresAt: dispatch.lease.expiresAt,
+            reservedUntil,
+            sandboxed: sandbox.executionMode === "docker",
+            resources: sandbox.requestedResources
+        });
+        await this.sendOfferDecision(dispatch, true, null, null, reservedUntil);
+    }
+    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;
+        }
+        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;
+            await this.sandboxRuntime.updateLease(request.dispatchAttemptId, request.fencingToken, request.expiresAt);
+        }
+    }
+    async sendOfferDecision(dispatch, accepted, code = null, message = null, reservedUntil = 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
+        };
+        await this.invokeAck("OfferDecision", payload);
+    }
     parseDispatchOrReport(rawDispatch) {
         try {
             return parseRunOnceDispatchPacket(rawDispatch);
@@ -137,7 +383,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,6 +401,14 @@ export class ForgeBridgeService {
         }
         active.controller.abort(request.reason ?? "cancelled by server");
     }
+    async handleReap(request) {
+        if (!this.config.dockerEnabled
+            || request.runnerId !== this.config.runnerId
+            || request.runnerInstanceId !== this.config.runnerInstanceId)
+            return;
+        await this.runSandboxMaintenance();
+        await this.sendHeartbeat();
+    }
     abortActiveSessions(reason) {
         for (const active of this.activeSessions.values()) {
             active.controller.abort(reason);
@@ -185,12 +439,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);
         }
@@ -209,12 +471,90 @@ export class ForgeBridgeService {
         }, intervalMs);
         this.heartbeatTimer.unref?.();
     }
+    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();
+        for (const [attemptId, reservation] of this.reservations) {
+            if (Date.parse(reservation.expiresAt) <= now || Date.parse(reservation.reservedUntil) <= now) {
+                this.reservations.delete(attemptId);
+            }
+        }
+        for (const active of this.activeSessions.values()) {
+            if (Date.parse(active.leaseExpiresAt) <= now && !active.controller.signal.aborted) {
+                active.controller.abort("dispatch lease expired");
+            }
+        }
+    }
     stopHeartbeat() {
         if (this.heartbeatTimer) {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
     }
+    startSandboxMaintenance() {
+        this.stopSandboxMaintenance();
+        if (!this.config.dockerEnabled)
+            return;
+        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 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() {
         await this.invokeAck("Heartbeat", {
             status: "online",
@@ -224,8 +564,13 @@ export class ForgeBridgeService {
         });
     }
     capabilities() {
+        const preflight = this.preflight.current();
+        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);
         return {
-            schemaVersion: 2,
+            schemaVersion: 3,
             activeSessionCount: this.activeSessions.size,
             cliProviders: this.config.cliProviders,
             providerStatuses: this.config.providerStatuses,
@@ -233,11 +578,56 @@ export class ForgeBridgeService {
             repoMappings: repoMappingsFor(this.config),
             os: this.config.os,
             sandboxProfiles: this.config.sandboxProfiles,
+            runnerInstanceId: this.config.runnerInstanceId,
+            trustDomainId: this.config.trustDomainId,
+            maxConcurrentSandboxes: preflight?.maxConcurrentSandboxes ?? 0,
+            reservedSandboxCount: reserved,
+            activeSandboxCount: runtimeState.active,
+            startingSandboxCount: runtimeState.starting,
+            degradedReservationCount: runtimeState.degraded,
+            sandboxRuntimes: preflight?.healthy ? ["docker"] : [],
+            sandboxRuntimeVersion: preflight?.runtimeVersion ?? null,
+            sandboxFeatures: preflight?.features ?? null,
+            sandboxPublicationModes: [this.config.sandboxPublicationMode ?? "shared_filesystem"],
+            sandboxAuthModes: sandboxAuthModesFor(this.config),
+            availableMemoryBytes: preflight ? Math.max(0, capacity.memoryBytes - used.memoryBytes) : 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.",
             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
+        };
+    }
+    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);
+    }
+    sandboxResourceCapacity(preflight) {
+        if (!preflight)
+            return zeroSandboxResources();
+        return {
+            sandboxSlots: preflight.maxConcurrentSandboxes,
+            cpuMillis: preflight.availableCpuMillis,
+            memoryBytes: Math.max(0, preflight.availableMemoryBytes - 2 * 1024 ** 3),
+            workspaceBytes: Math.max(0, preflight.availableWorkspaceBytes - this.config.minimumWorkspaceBytes),
+            pids: this.config.sandboxPidCapacity,
+            buildSlots: this.config.maxConcurrentSandboxBuilds
         };
     }
     async invokeAck(methodName, payload) {
@@ -259,6 +649,8 @@ export class ForgeBridgeService {
     }
     async stopConnection() {
         this.stopHeartbeat();
+        this.stopLeaseWatchdog();
+        this.stopSandboxMaintenance();
         if (this.connection) {
             await this.connection.stop().catch(() => undefined);
             this.connection = null;
@@ -303,6 +695,9 @@ export class SignalRBridgeConnection {
         })
             .configureLogging(LogLevel.Warning)
             .build();
+        this.connection.on("Superseded", () => {
+            void this.connection.stop();
+        });
     }
     start() {
         return this.connection.start();
@@ -318,11 +713,31 @@ export class SignalRBridgeConnection {
             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);
+        });
+    }
     invoke(methodName, payload) {
         return this.connection.invoke(methodName, payload);
     }
@@ -330,9 +745,28 @@ export class SignalRBridgeConnection {
 export function defaultBridgeServiceConfig(overrides = {}) {
     const defaults = defaultForgeBridgeConfig();
     const cliProviders = splitCsv(process.env.FORGE_CLI_PROVIDERS ?? "codex");
+    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",
+        sandboxPublicationMode,
+        dockerExecutable: process.env.FORGE_DOCKER_EXECUTABLE ?? "docker",
+        dockerContext: process.env.FORGE_DOCKER_CONTEXT ?? "",
+        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),
+        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,8 +782,10 @@ 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),
         reconnectBackoffMs: [1000, 2000, 5000, 10000, 30000],
@@ -357,7 +793,9 @@ export function defaultBridgeServiceConfig(overrides = {}) {
     };
     return {
         ...config,
+        providerStatuses: overrides.providerStatuses ?? providerStatusesFor(config.cliProviders),
         sandboxProfiles: config.sandboxProfiles ?? defaultSandboxProfiles(config.cliProviders),
+        supportsDraftImageAttachments: (overrides.supportsDraftImageAttachments ?? true) && supportsDraftImageAttachmentsFor(config.cliProviders),
         heartbeatIntervalMs: positiveFiniteNumber(config.heartbeatIntervalMs, 30_000)
     };
 }
@@ -376,6 +814,30 @@ function positiveFiniteNumber(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"];
@@ -539,9 +1001,111 @@ function abortPromise(signal) {
     }
     return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
 }
+export function canReapManagedSandboxes(preflight) {
+    return canRunDockerMaintenance(preflight);
+}
+function sandboxNetworkPolicyFailure(dispatch) {
+    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")) {
+        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;
+}
+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;
+}
+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;
+}
+function sumSandboxResources(resources) {
+    return resources.reduce((total, resource) => ({
+        sandboxSlots: total.sandboxSlots + resource.sandboxSlots,
+        cpuMillis: total.cpuMillis + resource.cpuMillis,
+        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, memoryBytes: 0, workspaceBytes: 0, pids: 0, buildSlots: 0 };
+}
+function defaultSandboxResources() {
+    return {
+        sandboxSlots: 1,
+        cpuMillis: 2000,
+        memoryBytes: 2 * 1024 ** 3,
+        workspaceBytes: 10 * 1024 ** 3,
+        pids: 512,
+        buildSlots: 0
+    };
+}
+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);
+}