@loucompanion/forge-bridge 0.1.3-dev.8777774c67bc → 0.1.3-dev.88e93f53db5b

package/dist/sandbox/runtime.js

@@ -10,8 +10,10 @@ import { evaluateSandboxImagePolicy, hasSandboxImagePolicyRecord, sandboxImagePo
 import { SandboxEventBudget } from "./event-budget.js";
 import { RepositoryCoordinatorLock } from "./repository-lock.js";
 import { redactText } from "../shared/redaction/redaction.js";
+import { createRuntimeIsolationLease, renewRuntimeIsolationLease, transitionRuntimeIsolationLease, validRuntimeIsolationLease, withRuntimeIsolationResources, } from "../runtime/runtime-isolation-lease.js";
 import { sandboxProviderAuthAdapterFor, sandboxProviderAuthUnavailableMessage } from "./provider-auth/codex.js";
 const managedLabel = "dev.forge.managed=true";
+const bridgeRuntimeDigestLabel = "dev.forge.bridge-runtime-digest";
 export class DockerSandboxRuntime {
     config;
     publicationGrantRedeemer;
@@ -31,12 +33,40 @@ export class DockerSandboxRuntime {
         const controller = new AbortController();
         const abort = () => controller.abort(signal?.reason ?? "sandbox cancelled");
         signal?.addEventListener("abort", abort, { once: true });
+        const runtimeLease = createRuntimeIsolationLease({
+            leaseId: dispatch.sandbox.executionLeaseId,
+            dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
+            executionLeaseId: dispatch.sandbox.executionLeaseId,
+            fencingToken: dispatch.lease.fencingToken,
+            runnerId: dispatch.execution.runnerId ?? "",
+            runnerInstanceId: dispatch.sandbox.runnerInstanceId,
+            worktreeKey: dispatch.lease.worktreeKey,
+            worktreePath: "/workspace",
+            mode: "docker",
+            expiresAt: dispatch.lease.expiresAt,
+            resources: {
+                memoryReservationBytes: dispatch.sandbox.requestedResources.memoryBytes,
+                cpuMillis: dispatch.sandbox.requestedResources.cpuMillis,
+                pids: dispatch.sandbox.requestedResources.pids,
+                ports: [],
+                paths: [
+                    { path: "/workspace", role: "worktree" },
+                    { path: "/tmp", role: "temporary" },
+                    { path: "/control/output/logs", role: "logs" },
+                    { path: "/tmp/forge-browser-profile", role: "browser_profile" },
+                ],
+                processSupervisorId: null,
+                dockerResources: [],
+                singletonKeys: [],
+            },
+        });
         const active = {
             dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
             fencingToken: dispatch.lease.fencingToken,
             expiresAt: dispatch.lease.expiresAt,
             controller,
             phase: "starting",
+            runtimeLease,
             ledger: null,
             leaseControlKey: randomBytes(32).toString("base64url")
         };
@@ -60,6 +90,7 @@ export class DockerSandboxRuntime {
             const git = new HostGit(this.config, repoPath);
             const prepared = await git.prepare(dispatch, attemptRoot, runtimeSignal);
             const validated = validateSandboxContract(prepared.contractSource);
+            validateSandboxMemoryReservation(dispatch, validated);
             validateDockerfilePolicy(prepared.dockerfile, dispatch.sandbox.executionPolicy === "sandbox_required");
             const upstreamImages = dockerfileUpstreamImages(prepared.dockerfile);
             const securityOptions = resolveSandboxSecurityOptions(dispatch.sandbox.executionPolicy);
@@ -78,20 +109,22 @@ export class DockerSandboxRuntime {
                 imageDigest
             }));
             const resources = resourceNames(identity.attemptHex, validated.contract.caches.filter(cache => cache.mode === "per_attempt").map(cache => cache.name));
-            const labels = labelsFor(runtimeDispatch, imageDigest, validated.digest);
-            const networkArgs = networkCreateArgs(runtimeDispatch);
+            const labels = sandboxResourceLabels(runtimeDispatch, imageDigest, validated.digest);
+            const networkArgs = networkCreateArgs(runtimeDispatch, process.env, this.config.allowOpenPublicSandbox);
+            active.runtimeLease = withRuntimeIsolationResources(transitionRuntimeIsolationLease(active.runtimeLease, "starting"), {
+                ...active.runtimeLease.resources,
+                dockerResources: plannedDockerLeaseResources(resources, runtimeDispatch.sandbox.networkPolicy.mode === "public_allowlist", Boolean(providerAuthAdapter)),
+            });
             active.ledger = {
-                schemaVersion: 1,
-                dispatchAttemptId: active.dispatchAttemptId,
-                fencingToken: active.fencingToken,
-                runnerInstanceId: this.config.runnerInstanceId,
-                expiresAt: active.expiresAt,
+                schemaVersion: 3,
+                runtimeLease: active.runtimeLease,
                 resources,
                 labels,
                 includeCredentials: Boolean(providerAuthAdapter)
             };
             await this.writeLedger(active.ledger);
             let teardownComplete = false;
+            let memoryTelemetryEvent = null;
             try {
                 const internalNetworkId = dockerObjectId((await this.docker(["network", "create", ...networkArgs, ...labelArgs(labels), resources.network], 30_000, runtimeSignal)).stdout, "network");
                 await this.docker(["volume", "create", ...labelArgs(labels), resources.workspaceVolume], 30_000, runtimeSignal);
@@ -108,32 +141,47 @@ export class DockerSandboxRuntime {
                     egressNetworkId = dockerObjectId((await this.docker(["network", "create", ...labelArgs(labels), resources.egressNetwork], 30_000, runtimeSignal)).stdout, "network");
                     await this.docker(["volume", "create", ...labelArgs(labels), resources.egressConfigVolume], 30_000, runtimeSignal);
                 }
-                await this.initializeVolumes(builtImage.helperImageDigest, resources, Boolean(providerAuthAdapter), runtimeSignal);
-                await this.initializeProviderCredentials(builtImage.helperImageDigest, runtimeDispatch, resources, runtimeSignal);
+                await this.initializeVolumes(builtImage.helperImageDigest, resources, labels, Boolean(providerAuthAdapter), runtimeSignal);
+                await this.initializeProviderCredentials(builtImage.helperImageDigest, runtimeDispatch, resources, labels, runtimeSignal);
                 await sink.emit(event("sandbox_cache_policy", "Runtime caches are builder-managed or isolated to this attempt.", {
                     builderManaged: validated.contract.caches.filter(cache => cache.mode === "readonly").map(cache => cache.name),
                     perAttempt: Object.keys(resources.cacheVolumes)
                 }));
-                await this.initializeServiceSecrets(builtImage.helperImageDigest, validated, resources, runtimeSignal);
-                await this.initializeEgressPolicy(builtImage.helperImageDigest, runtimeDispatch, resources, runtimeSignal);
+                await this.initializeServiceSecrets(builtImage.helperImageDigest, validated, resources, labels, runtimeSignal);
+                await this.initializeEgressPolicy(builtImage.helperImageDigest, runtimeDispatch, resources, labels, runtimeSignal);
                 const egressProxy = await this.startEgressProxy(runtimeDispatch, resources, labels, securityOptions, sink, runtimeSignal);
                 const serviceContainers = await this.startServices(validated, runtimeDispatch.sandbox.executionPolicy, resources, labels, securityOptions, sink, runtimeSignal);
                 const createArgs = workerCreateArgs(runtimeDispatch, validated, resources, labels, imageDigest, securityOptions);
                 const createdContainer = await this.docker(createArgs, 60_000, runtimeSignal);
                 const containerId = dockerObjectId(createdContainer.stdout, "container");
                 await this.docker(["cp", prepared.bundlePath, `${containerId}:/control/input/repo.bundle`], 60_000, runtimeSignal);
+                const runtimeContainers = [
+                    { id: containerId, name: resources.container, role: "agent" },
+                    ...(egressProxy ? [egressProxy] : []),
+                    ...serviceContainers
+                ];
+                active.runtimeLease = withRuntimeIsolationResources(transitionRuntimeIsolationLease(active.runtimeLease, "active"), {
+                    ...active.runtimeLease.resources,
+                    dockerResources: activeDockerLeaseResources(runtimeContainers, [
+                        { id: internalNetworkId, name: resources.network, role: "internal" },
+                        ...(egressNetworkId ? [{ id: egressNetworkId, name: resources.egressNetwork, role: "egress" }] : []),
+                    ], sandboxRuntimeVolumes(resources, runtimeDispatch.sandbox.networkPolicy.mode === "public_allowlist", Boolean(providerAuthAdapter))),
+                });
+                active.ledger = { ...active.ledger, runtimeLease: active.runtimeLease };
+                await this.writeLedger(active.ledger);
                 await sink.emit(event("sandbox_started", `Docker sandbox ${identity.attemptHex} started.`, {
-                    agentContainer: { id: containerId, name: resources.container, role: "agent" },
+                    agentContainer: runtimeContainers[0],
                     sidecarContainers: [...(egressProxy ? [egressProxy] : []), ...serviceContainers],
                     networks: [
                         { id: internalNetworkId, name: resources.network, role: "internal" },
                         ...(egressNetworkId ? [{ id: egressNetworkId, name: resources.egressNetwork, role: "egress" }] : [])
                     ],
                     volumes: sandboxRuntimeVolumes(resources, runtimeDispatch.sandbox.networkPolicy.mode === "public_allowlist", Boolean(providerAuthAdapter)),
-                    publishedPorts: []
+                    publishedPorts: [],
+                    runtimeLease: active.runtimeLease,
                 }));
                 const eventBudget = new SandboxEventBudget();
-                const start = await runSandboxProcess({
+                const startPromise = runSandboxProcess({
                     command: this.config.dockerExecutable,
                     args: this.dockerArgs(["start", "--attach", "--interactive", containerId]),
                     input: JSON.stringify({
@@ -156,6 +204,18 @@ export class DockerSandboxRuntime {
                         }
                     }
                 });
+                const memorySampler = this.startPeakMemorySampler(runtimeContainers);
+                const start = await startPromise.finally(async () => {
+                    const telemetry = await memorySampler.stop();
+                    if (!telemetry)
+                        return;
+                    memoryTelemetryEvent = event("sandbox_peak_memory_observed", `Observed sandbox peak memory ${formatMemoryBytes(telemetry.peakMemoryBytes)} across ${telemetry.containers.length} container${telemetry.containers.length === 1 ? "" : "s"} from ${telemetry.sampleCount} sample${telemetry.sampleCount === 1 ? "" : "s"}.`, { ...telemetry });
+                    if (active.ledger) {
+                        active.ledger = { ...active.ledger, peakMemory: telemetry };
+                        await this.writeLedger(active.ledger).catch(() => undefined);
+                    }
+                    await sink.emit(memoryTelemetryEvent).catch(() => undefined);
+                });
                 if (start.truncated)
                     throw new Error("sandbox_log_limit: sandbox output exceeded the 8 MiB supervisor capture budget.");
                 const containerState = await this.inspectContainerState(containerId);
@@ -176,7 +236,16 @@ export class DockerSandboxRuntime {
                     workerExitCode: start.exitCode
                 }));
                 await this.docker(["cp", `${containerId}:/control/output/.`, path.join(attemptRoot, "output")], 60_000);
-                const output = await validateOutput(attemptRoot, runtimeDispatch);
+                let output;
+                try {
+                    output = await validateOutput(attemptRoot, runtimeDispatch);
+                }
+                catch (error) {
+                    if (start.exitCode !== 0 && isMissingSandboxManifest(error)) {
+                        throw new Error(sandboxWorkerFailureMessage(start.exitCode, start.stderr, containerState.error), { cause: error });
+                    }
+                    throw error;
+                }
                 await git.importResult(runtimeDispatch, output, () => assertSandboxImportCurrent(active, this.active.get(active.dispatchAttemptId), controller.signal));
                 if (runtimeDispatch.sandbox.publicationMode === "bridge_push") {
                     const handle = runtimeDispatch.sandbox.publishGrantHandle;
@@ -207,36 +276,49 @@ export class DockerSandboxRuntime {
                         ...result.events.flatMap(resultEvent => [resultEvent.eventType, resultEvent.content, resultEvent.data ?? ""])
                     ].join("\n"));
                     if (resourceFailure) {
-                        return {
+                        return appendRunOnceEvent({
                             ...result,
                             summary: resourceFailure.message,
                             events: [...result.events, event(resourceFailure.code, resourceFailure.message, { phase: "agent" })]
-                        };
+                        }, memoryTelemetryEvent);
                     }
                 }
                 await sink.emit(event("sandbox_output_imported", "Validated and imported sandbox output.", {
                     resultCommitSha: output.manifest.resultCommitSha,
                 }));
-                return result;
+                return appendRunOnceEvent(result, memoryTelemetryEvent);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 const classified = classifySandboxRuntimeFailure(message);
-                return failureResult(classified.message, [event(classified.code, classified.message, { phase: classified.phase })]);
+                return appendRunOnceEvent(failureResult(classified.message, [event(classified.code, classified.message, { phase: classified.phase })]), memoryTelemetryEvent);
             }
             finally {
                 try {
                     try {
-                        await sink.emit(event("sandbox_teardown_started", `Removing Docker resources for attempt ${active.dispatchAttemptId}.`)).catch(() => undefined);
+                        active.runtimeLease = transitionForCleanup(active.runtimeLease, "releasing");
+                        if (active.ledger) {
+                            active.ledger = { ...active.ledger, runtimeLease: active.runtimeLease };
+                            await this.writeLedger(active.ledger);
+                        }
+                        await sink.emit(event("sandbox_teardown_started", `Removing Docker resources for attempt ${active.dispatchAttemptId}.`, {
+                            runtimeLease: active.runtimeLease,
+                        })).catch(() => undefined);
                         const cleanupReport = await this.teardown(resources, labels, "teardown", Boolean(providerAuthAdapter));
                         await this.persistCleanupReport(cleanupReport);
                         teardownComplete = true;
+                        active.runtimeLease = transitionRuntimeIsolationLease(active.runtimeLease, "released");
                         this.degraded.delete(active.dispatchAttemptId);
                         await this.removeLedger(active.dispatchAttemptId);
                         await sink.emit(event("sandbox_teardown_completed", `Removed Docker resources for attempt ${active.dispatchAttemptId}.`, { ...cleanupReport })).catch(() => undefined);
                     }
                     catch (error) {
                         this.degraded.add(active.dispatchAttemptId);
+                        active.runtimeLease = transitionForCleanup(active.runtimeLease, "degraded");
+                        if (active.ledger) {
+                            active.ledger = { ...active.ledger, runtimeLease: active.runtimeLease };
+                            await this.writeLedger(active.ledger).catch(() => undefined);
+                        }
                         const cleanupReport = error instanceof SandboxTeardownError ? error.report : emptyCleanupReport("teardown");
                         await this.persistCleanupReport(cleanupReport);
                         await sink.emit(event("teardown_failed", `Docker resources for attempt ${active.dispatchAttemptId} require reaping.`, { ...cleanupReport })).catch(() => undefined);
@@ -255,14 +337,16 @@ export class DockerSandboxRuntime {
         }
     }
     async updateLease(dispatchAttemptId, fencingToken, expiresAt) {
-        if (!Number.isFinite(Date.parse(expiresAt)))
-            return;
         const active = this.active.get(dispatchAttemptId);
         if (!active || active.fencingToken !== fencingToken)
             return;
+        const renewed = renewRuntimeIsolationLease(active.runtimeLease, fencingToken, expiresAt);
+        if (!renewed)
+            return;
         active.expiresAt = expiresAt;
+        active.runtimeLease = renewed;
         if (active.ledger) {
-            active.ledger = { ...active.ledger, expiresAt };
+            active.ledger = { ...active.ledger, runtimeLease: renewed };
             await this.writeLedger(active.ledger);
             await this.pushLeaseUpdate(active).catch(() => undefined);
         }
@@ -303,29 +387,34 @@ export class DockerSandboxRuntime {
         for (const ledger of await this.readLedgers()) {
             if (ledger.labels["dev.forge.runner-id"] !== this.config.runnerId)
                 continue;
-            const current = this.active.get(ledger.dispatchAttemptId);
+            const lease = ledger.runtimeLease;
+            const current = this.active.get(lease.dispatchAttemptId);
             if (current
-                && current.fencingToken === ledger.fencingToken
-                && ledger.runnerInstanceId === this.config.runnerInstanceId) {
-                liveAttempts.add(ledger.dispatchAttemptId);
+                && current.fencingToken === lease.fencingToken
+                && lease.runnerInstanceId === this.config.runnerInstanceId) {
+                liveAttempts.add(lease.dispatchAttemptId);
                 continue;
             }
-            const serverAttempt = snapshotByAttempt.get(ledger.dispatchAttemptId);
+            const serverAttempt = snapshotByAttempt.get(lease.dispatchAttemptId);
             if (!shouldReapSandboxLedger(ledger, this.config.runnerInstanceId, serverAttempt, options.attemptSnapshot !== undefined, now)) {
-                liveAttempts.add(ledger.dispatchAttemptId);
+                liveAttempts.add(lease.dispatchAttemptId);
                 continue;
             }
             try {
+                const releasing = transitionForCleanup(lease, "releasing");
+                await this.writeLedger({ ...ledger, runtimeLease: releasing });
                 const report = await this.teardown(ledger.resources, ledger.labels, "reaper", ledger.includeCredentials !== false);
                 await this.persistCleanupReport(report);
-                await this.removeLedger(ledger.dispatchAttemptId);
-                this.degraded.delete(ledger.dispatchAttemptId);
-                await fs.rm(path.join(this.config.sandboxStateRoot, "attempts", ledger.dispatchAttemptId.replace(/-/g, "").toLowerCase()), { recursive: true, force: true }).catch(() => undefined);
+                await this.removeLedger(lease.dispatchAttemptId);
+                this.degraded.delete(lease.dispatchAttemptId);
+                await fs.rm(path.join(this.config.sandboxStateRoot, "attempts", lease.dispatchAttemptId.replace(/-/g, "").toLowerCase()), { recursive: true, force: true }).catch(() => undefined);
             }
             catch (error) {
                 if (error instanceof SandboxTeardownError)
                     await this.persistCleanupReport(error.report);
-                this.degraded.add(ledger.dispatchAttemptId);
+                const degraded = transitionForCleanup(lease, "degraded");
+                await this.writeLedger({ ...ledger, runtimeLease: degraded }).catch(() => undefined);
+                this.degraded.add(lease.dispatchAttemptId);
             }
         }
         for (const kind of ["container", "network", "volume"]) {
@@ -337,9 +426,14 @@ export class DockerSandboxRuntime {
             }
         }
         await this.purgeRestrictedAuditArtifacts();
-        if (options.diskLow) {
-            await this.withBuildPermit(() => this.collectExpiredImages());
-        }
+        await this.withBuildPermit(async () => {
+            if (options.diskLow) {
+                await this.collectExpiredImages();
+            }
+            if (this.active.size === 0 && this.builds.size === 0) {
+                await this.stopBuildxBuilder().catch(() => undefined);
+            }
+        });
     }
     async pendingCleanupReports() {
         const root = path.join(this.config.sandboxStateRoot, "cleanup-reports");
@@ -399,7 +493,7 @@ export class DockerSandboxRuntime {
     async writeLedger(ledger) {
         const root = path.join(this.config.sandboxStateRoot, "ledger");
         await fs.mkdir(root, { recursive: true, mode: 0o700 });
-        const target = this.ledgerPath(ledger.dispatchAttemptId);
+        const target = this.ledgerPath(ledger.runtimeLease.dispatchAttemptId);
         const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
         const handle = await fs.open(temporary, "wx", 0o600);
         try {
@@ -422,8 +516,8 @@ export class DockerSandboxRuntime {
             const stat = await fs.lstat(target);
             if (stat.isSymbolicLink() || stat.size > 64 * 1024)
                 continue;
-            const ledger = JSON.parse(await fs.readFile(target, "utf8"));
-            if (validLedger(ledger))
+            const ledger = normalizeSandboxLedger(JSON.parse(await fs.readFile(target, "utf8")));
+            if (ledger)
                 result.push(ledger);
         }
         return result;
@@ -446,17 +540,20 @@ export class DockerSandboxRuntime {
         if (!/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(codexVersion))
             throw new Error("sandbox_build_failed: invalid pinned Codex package version.");
         const policyConfigurationDigest = await sandboxImagePolicyConfigurationDigest();
-        const key = createHash("sha256").update([
+        const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+        const bridgeRuntimeDigest = await bridgeRuntimeContentDigest(packageRoot);
+        const key = sandboxImageCacheKey({
             contextDigest,
-            contract.digest,
-            process.platform,
-            process.arch,
-            this.config.version,
+            contractDigest: contract.digest,
+            platform: process.platform,
+            architecture: process.arch,
+            bridgeVersion: this.config.version,
+            bridgeRuntimeDigest,
             toolingImage,
             codexVersion,
             policy,
             policyConfigurationDigest
-        ].join("\0")).digest("hex");
+        });
         const existing = this.builds.get(key);
         if (existing) {
             await sink.emit(event("sandbox_image_cache_miss", `Sandbox image ${key.slice(0, 12)} is being built by another dispatch.`, { cacheKey: key, singleflight: true }));
@@ -468,7 +565,16 @@ export class DockerSandboxRuntime {
             }));
             return built;
         }
-        const promise = this.withBuildPermit(() => this.buildImageCore(contextRoot, contextDigest, contract.digest, key, project, toolingImage, upstreamImages, codexVersion, policy, sink, signal), signal);
+        const promise = this.withBuildPermit(async () => {
+            try {
+                return await this.buildImageCore(contextRoot, contextDigest, contract.digest, key, project, packageRoot, bridgeRuntimeDigest, toolingImage, upstreamImages, codexVersion, policy, sink, signal);
+            }
+            finally {
+                await this.stopBuildxBuilder().catch(async (error) => {
+                    await sink.emit(event("sandbox_builder_release_failed", `The dedicated BuildKit builder could not be stopped: ${error instanceof Error ? error.message : String(error)}.`)).catch(() => undefined);
+                });
+            }
+        }, signal);
         this.builds.set(key, promise);
         try {
             return await promise;
@@ -492,16 +598,16 @@ export class DockerSandboxRuntime {
             release();
         }
     }
-    async buildImageCore(contextRoot, contextDigest, contractDigest, key, project, toolingImage, upstreamImages, codexVersion, policy, sink, signal) {
+    async buildImageCore(contextRoot, contextDigest, contractDigest, key, project, packageRoot, bridgeRuntimeDigest, toolingImage, upstreamImages, codexVersion, policy, sink, signal) {
         const projectTag = `forge/project:${key}`;
         const helperTag = `forge/tooling:${key}`;
         const overlayTag = `forge/agent:${key}`;
         const [cachedHelper, cachedOverlay] = await Promise.all([
-            this.docker(["image", "inspect", helperTag, "--format", "{{.Id}}"], 15_000).catch(() => null),
-            this.docker(["image", "inspect", overlayTag, "--format", "{{.Id}}"], 15_000).catch(() => null)
+            this.inspectImageMetadata(helperTag),
+            this.inspectImageMetadata(overlayTag)
         ]);
-        const cachedHelperDigest = cachedHelper?.stdout.trim() ?? "";
-        const cachedOverlayDigest = cachedOverlay?.stdout.trim() ?? "";
+        const cachedHelperDigest = cachedHelper?.id ?? "";
+        const cachedOverlayDigest = cachedOverlay?.id ?? "";
         const cacheRecordPath = path.join(this.config.sandboxStateRoot, "image-cache", `${key}.json`);
         const cacheRecord = await this.readImageCacheRecord(cacheRecordPath);
         const policyRecordValid = cacheRecord?.policyDigest
@@ -511,6 +617,7 @@ export class DockerSandboxRuntime {
             && /^sha256:[0-9a-f]{64}$/i.test(cachedOverlayDigest)
             && cacheRecord?.helperImageDigest === cachedHelperDigest
             && cacheRecord.imageDigest === cachedOverlayDigest
+            && bridgeRuntimeCacheMatches(cacheRecord, bridgeRuntimeDigest, [cachedHelper?.labels, cachedOverlay?.labels])
             && policyRecordValid) {
             await this.writeImageCacheRecord({
                 ...cacheRecord,
@@ -530,29 +637,44 @@ export class DockerSandboxRuntime {
         await sink.emit(event("sandbox_build_started", `Building sandbox image ${key.slice(0, 12)}.`, { cacheKey: key }));
         const builder = await this.ensureBuildxBuilder(signal);
         const metadataRoot = path.join(this.config.sandboxStateRoot, "attestations", key, "buildkit");
-        await fs.mkdir(metadataRoot, { recursive: true, mode: 0o700 });
-        const cached = await this.docker(["image", "inspect", projectTag, "--format", "{{.Id}}"], 15_000).catch(() => null);
-        let projectImage = cached?.stdout.trim();
-        if (!projectImage) {
-            await this.runBuildStage("project", key, buildxBuildArgs(builder, path.join(metadataRoot, "project.json"), ["--pull=false", ...imageLabelArgs(project, key, "project"), "--tag", projectTag, "--file", path.join(contextRoot, ".forge", "Dockerfile"), contextRoot]), sink, signal);
-            projectImage = (await this.docker(["image", "inspect", projectTag, "--format", "{{.Id}}"], 15_000)).stdout.trim();
-        }
-        if (!/^sha256:[0-9a-f]{64}$/i.test(projectImage))
-            throw new Error("sandbox_build_failed: project image did not resolve to an immutable digest.");
         const overlayRoot = path.join(this.config.sandboxStateRoot, "build", `overlay-${key}`);
-        await fs.rm(overlayRoot, { recursive: true, force: true });
-        await fs.mkdir(path.join(overlayRoot, "bridge"), { recursive: true });
-        const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-        await fs.cp(path.join(packageRoot, "dist"), path.join(overlayRoot, "bridge", "dist"), { recursive: true });
-        await fs.copyFile(path.join(packageRoot, "package.json"), path.join(overlayRoot, "bridge", "package.json"));
-        await fs.copyFile(path.join(packageRoot, "package-lock.json"), path.join(overlayRoot, "bridge", "package-lock.json"));
-        const dockerfile = `FROM ${toolingImage} AS tooling\nWORKDIR /opt/forge-bridge\nCOPY bridge/package*.json ./\nRUN npm ci --omit=dev --ignore-scripts && npm install --global @openai/codex@${codexVersion} && npm cache clean --force\nCOPY bridge/dist ./dist\nFROM ${projectImage}\nUSER 0\nCOPY --from=tooling /usr/local/bin/node /usr/local/bin/node\nCOPY --from=tooling /usr/local/bin/codex /usr/local/bin/codex\nCOPY --from=tooling /usr/local/lib/node_modules/@openai/codex /usr/local/lib/node_modules/@openai/codex\nCOPY --from=tooling /opt/forge-bridge /opt/forge-bridge\nRUN (getent group 10001 || groupadd -g 10001 forge) && (getent passwd 10001 || useradd -u 10001 -g 10001 -d /home/forge -m forge)\nENV HOME=/home/forge TMPDIR=/tmp\nENTRYPOINT []\nCMD []\nUSER 10001:10001\n`;
+        await prepareOverlayBuildRoot(overlayRoot);
+        await fs.mkdir(metadataRoot, { recursive: true, mode: 0o700 });
+        const projectOciArchive = path.join(overlayRoot, "project.oci.tar");
+        const projectOciRoot = path.join(overlayRoot, "project-oci");
+        await this.runBuildStage("project", key, buildxBuildArgs(builder, path.join(metadataRoot, "project.json"), [
+            "--pull=false",
+            ...imageLabelArgs(project, key, "project", bridgeRuntimeDigest),
+            "--tag", projectTag,
+            "--output", `type=oci,dest=${projectOciArchive}`,
+            "--file", path.join(contextRoot, ".forge", "Dockerfile"),
+            contextRoot
+        ], process.env, { load: false }), sink, signal);
+        await extractOciLayoutArchive(projectOciArchive, projectOciRoot, signal);
+        const projectImage = await readOciLayoutImageDigest(projectOciRoot);
+        const projectContextName = "forge_project";
+        const stagedBridgeRoot = path.join(overlayRoot, "bridge");
+        await fs.cp(path.join(packageRoot, "dist"), path.join(stagedBridgeRoot, "dist"), { recursive: true });
+        const installMode = await copyBridgePackageManifests(packageRoot, stagedBridgeRoot);
+        const stagedBridgeRuntimeDigest = await bridgeRuntimeContentDigest(stagedBridgeRoot);
+        if (stagedBridgeRuntimeDigest !== bridgeRuntimeDigest) {
+            throw new Error("sandbox_build_failed: bridge runtime payload changed while preparing the sandbox image; retry the dispatch.");
+        }
+        const dockerfile = agentOverlayDockerfile(toolingImage, projectContextName, installMode, codexVersion);
         await fs.writeFile(path.join(overlayRoot, "Dockerfile"), dockerfile);
-        await this.runBuildStage("tooling", key, buildxBuildArgs(builder, path.join(metadataRoot, "tooling.json"), ["--pull=false", "--target", "tooling", ...imageLabelArgs(project, key, "tooling"), "--tag", helperTag, overlayRoot]), sink, signal);
+        await fs.writeFile(path.join(overlayRoot, ".dockerignore"), agentOverlayDockerignore());
+        await this.runBuildStage("tooling", key, buildxBuildArgs(builder, path.join(metadataRoot, "tooling.json"), ["--pull=false", "--target", "tooling", ...imageLabelArgs(project, key, "tooling", bridgeRuntimeDigest), "--tag", helperTag, overlayRoot]), sink, signal);
         const helperImageDigest = (await this.docker(["image", "inspect", helperTag, "--format", "{{.Id}}"], 15_000)).stdout.trim();
         if (!/^sha256:[0-9a-f]{64}$/i.test(helperImageDigest))
             throw new Error("sandbox_build_failed: helper image did not resolve to an immutable digest.");
-        await this.runBuildStage("agent", key, buildxBuildArgs(builder, path.join(metadataRoot, "agent.json"), ["--pull=false", ...imageLabelArgs(project, key, "agent"), "--tag", overlayTag, overlayRoot]), sink, signal);
+        const projectContextRef = ociLayoutContextRef(path.relative(overlayRoot, projectOciRoot));
+        await this.runBuildStage("agent", key, buildxBuildArgs(builder, path.join(metadataRoot, "agent.json"), [
+            "--pull=false",
+            "--build-context", `${projectContextName}=${projectContextRef}`,
+            ...imageLabelArgs(project, key, "agent", bridgeRuntimeDigest),
+            "--tag", overlayTag,
+            "."
+        ]), sink, signal, { cwd: overlayRoot });
         const digest = (await this.docker(["image", "inspect", overlayTag, "--format", "{{.Id}}"], 15_000)).stdout.trim();
         if (!/^sha256:[0-9a-f]{64}$/i.test(digest))
             throw new Error("sandbox_build_failed: overlay image did not resolve to an immutable digest.");
@@ -568,9 +690,11 @@ export class DockerSandboxRuntime {
             upstreamImages,
             codexVersion,
             images: { project: projectImage, tooling: helperImageDigest, agent: digest },
+            imageScanTargets: { project: ociLayoutScanTarget(projectOciRoot) },
             signal
         });
         await sink.emit(event(imagePolicy.status === "passed" ? "sandbox_image_policy_passed" : "sandbox_image_policy_warning", imagePolicy.status === "passed" ? `Image policy passed for ${digest}.` : `Image attestations are incomplete for adoption-mode image ${digest}.`, { policyDigest: imagePolicy.policyDigest }));
+        await removeExtractedOciLayout(projectOciRoot);
         await this.writeImageCacheRecord({
             schemaVersion: 1,
             key,
@@ -582,6 +706,7 @@ export class DockerSandboxRuntime {
             overlayTag,
             imageDigest: digest,
             helperImageDigest,
+            bridgeRuntimeDigest,
             policyDigest: imagePolicy.policyDigest
         });
         await sink.emit(event("sandbox_build_completed", `Sandbox image ready at ${digest}.`, {
@@ -590,10 +715,11 @@ export class DockerSandboxRuntime {
         }));
         return { imageDigest: digest, helperImageDigest };
     }
-    async runBuildStage(stage, key, args, sink, signal) {
+    async runBuildStage(stage, key, args, sink, signal, options = {}) {
         const result = await runSandboxProcess({
             command: this.config.dockerExecutable,
             args: this.dockerArgs(args),
+            cwd: options.cwd,
             timeoutMs: 30 * 60_000,
             maxOutputBytes: 2 * 1024 * 1024,
             terminateOnOutputLimit: true,
@@ -635,21 +761,35 @@ export class DockerSandboxRuntime {
             await this.docker(["buildx", "create", "--name", name, "--driver", "docker-container"], 60_000, signal);
         }
         await this.docker(["buildx", "inspect", "--bootstrap", name], 2 * 60_000, signal, 1024 * 1024);
-        const pidsLimit = buildResourcePolicy().builderPidsLimit;
+        const policy = buildResourcePolicy();
         const container = dedicatedBuildxBuilderContainerName(name);
-        await this.docker(["container", "update", "--pids-limit", String(pidsLimit), container], 30_000, signal);
-        const applied = await this.docker(["container", "inspect", container, "--format", "{{.HostConfig.PidsLimit}}"], 30_000, signal);
-        if (Number(applied.stdout.trim()) !== pidsLimit) {
-            throw new Error("sandbox_build_policy_failed: dedicated BuildKit builder PID limit was not applied.");
+        await this.docker([
+            "container", "update",
+            "--pids-limit", String(policy.builderPidsLimit),
+            "--memory", String(policy.builderMemoryBytes),
+            "--memory-swap", String(policy.builderMemoryBytes),
+            container
+        ], 30_000, signal);
+        const applied = await this.docker(["container", "inspect", container, "--format", "{{json .HostConfig}}"], 30_000, signal);
+        const hostConfig = JSON.parse(applied.stdout);
+        if (Number(hostConfig.PidsLimit) !== policy.builderPidsLimit
+            || Number(hostConfig.Memory) !== policy.builderMemoryBytes
+            || Number(hostConfig.MemorySwap) !== policy.builderMemoryBytes) {
+            throw new Error("sandbox_build_policy_failed: dedicated BuildKit builder resource limits were not applied.");
         }
         return name;
     }
-    async initializeVolumes(helperImage, resources, includeCredentials, signal) {
+    async stopBuildxBuilder() {
+        const name = dedicatedBuildxBuilderName(this.config.runnerId, this.config.dockerContext);
+        const container = dedicatedBuildxBuilderContainerName(name);
+        await this.docker(["container", "stop", "--time", "10", container], 30_000);
+    }
+    async initializeVolumes(helperImage, resources, labels, includeCredentials, signal) {
         const cacheMounts = Object.entries(resources.cacheVolumes).flatMap(([name, volume]) => ["--volume", `${volume}:/cache/${name}`]);
-        const credentialSetup = includeCredentials ? "f.chownSync('/credentials',10001,10001);f.chmodSync('/credentials',0o700);" : "";
-        const script = `const f=require('fs');f.mkdirSync('/control/input',{recursive:true});f.mkdirSync('/control/output',{recursive:true});for(const p of ['/control','/control/input','/control/output','/workspace'])f.chmodSync(p,0o777);${credentialSetup}for(const p of f.readdirSync('/cache').map(n=>'/cache/'+n)){f.chownSync(p,10001,10001);f.chmodSync(p,0o700)}`;
+        const credentialSetup = includeCredentials ? "f.chmodSync('/credentials',0o700);" : "";
+        const script = `const f=require('fs'),owned=['/control','/control/input','/control/output','/workspace'];f.mkdirSync('/control/input',{recursive:true});f.mkdirSync('/control/output',{recursive:true});for(const p of owned)f.chmodSync(p,0o700);for(const p of owned.toReversed())f.chownSync(p,10001,10001);${credentialSetup}for(const p of f.readdirSync('/cache').map(n=>'/cache/'+n)){f.chmodSync(p,0o700);f.chownSync(p,10001,10001)}`;
         const credentialMount = includeCredentials ? ["--volume", `${resources.credentialsVolume}:/credentials`] : [];
-        await this.docker(["run", "--rm", "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.workspaceVolume}:/workspace`, "--volume", `${resources.controlVolume}:/control`, ...credentialMount, ...cacheMounts, "--tmpfs", "/cache:rw,nosuid,nodev,noexec,size=1m", helperImage, "-e", script], 60_000, signal);
+        await this.docker(["run", "--rm", ...labelArgs(labels), "--network", "none", "--read-only", "--cap-drop", "ALL", "--cap-add", "CHOWN", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.workspaceVolume}:/workspace`, "--volume", `${resources.controlVolume}:/control`, ...credentialMount, ...cacheMounts, "--tmpfs", "/cache:rw,nosuid,nodev,noexec,size=1m", helperImage, "-e", script], 60_000, signal);
     }
     async inspectContainerState(containerId) {
         const result = await this.docker(["container", "inspect", containerId, "--format", "{{json .State}}"], 15_000, undefined, 256 * 1024);
@@ -660,14 +800,14 @@ export class DockerSandboxRuntime {
             error: typeof value.Error === "string" && value.Error.trim() ? value.Error.trim().slice(0, 1000) : null
         };
     }
-    async initializeServiceSecrets(helperImage, contract, resources, signal) {
+    async initializeServiceSecrets(helperImage, contract, resources, labels, signal) {
         const script = "let s='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>require('fs').writeFileSync('/secrets/postgres-password',s,{mode:0o444}))";
         for (const service of contract.contract.services) {
             const secretName = service.type === "postgres" ? "postgres-password" : service.type === "redis" ? "redis-password" : "browser-token";
             const writeScript = script.replace("postgres-password", secretName);
             await requireSandboxProcess({
                 command: this.config.dockerExecutable,
-                args: this.dockerArgs(["run", "--rm", "--interactive", "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.secretsVolume}:/secrets`, helperImage, "-e", writeScript]),
+                args: this.dockerArgs(["run", "--rm", "--interactive", ...labelArgs(labels), "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.secretsVolume}:/secrets`, helperImage, "-e", writeScript]),
                 input: randomBytes(32).toString("base64url"),
                 timeoutMs: 60_000,
                 maxOutputBytes: 64 * 1024,
@@ -675,28 +815,28 @@ export class DockerSandboxRuntime {
             });
         }
     }
-    async initializeProviderCredentials(helperImage, dispatch, resources, signal) {
+    async initializeProviderCredentials(helperImage, dispatch, resources, labels, signal) {
         const providerAuth = await sandboxProviderAuthForDispatch(dispatch);
         if (!providerAuth) {
             return;
         }
-        const script = "let s='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{const f=require('fs'),p=require('path'),root='/credentials';for(const e of f.readdirSync(root))f.rmSync(p.join(root,e),{recursive:true,force:true});const packet=JSON.parse(s);for(const file of packet.files){if(!/^[a-z0-9_.-]+$/i.test(file.name))throw new Error('invalid credential file');const target=p.resolve(root,file.name);if(!target.startsWith(root+'/'))throw new Error('invalid credential file');const body=Buffer.from(file.contentBase64,'base64');f.writeFileSync(target,body,{mode:0o600});f.chownSync(target,10001,10001)}f.chownSync(root,10001,10001);f.chmodSync(root,0o700)})";
+        const script = "let s='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{const f=require('fs'),p=require('path'),root='/credentials';for(const e of f.readdirSync(root))f.rmSync(p.join(root,e),{recursive:true,force:true});const packet=JSON.parse(s);for(const file of packet.files){if(!/^[a-z0-9_.-]+$/i.test(file.name))throw new Error('invalid credential file');const target=p.resolve(root,file.name);if(!target.startsWith(root+'/'))throw new Error('invalid credential file');const body=Buffer.from(file.contentBase64,'base64');f.writeFileSync(target,body,{mode:0o600});f.chmodSync(target,0o600);f.chownSync(target,10001,10001)}f.chmodSync(root,0o700);f.chownSync(root,10001,10001)})";
         await requireSandboxProcess({
             command: this.config.dockerExecutable,
-            args: this.dockerArgs(["run", "--rm", "--interactive", "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.credentialsVolume}:/credentials`, helperImage, "-e", script]),
+            args: this.dockerArgs(["run", "--rm", "--interactive", ...labelArgs(labels), "--network", "none", "--read-only", "--cap-drop", "ALL", "--cap-add", "CHOWN", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.credentialsVolume}:/credentials`, helperImage, "-e", script]),
             input: JSON.stringify({ files: providerAuth.files }),
             timeoutMs: 60_000,
             maxOutputBytes: 64 * 1024,
             signal
         });
     }
-    async initializeEgressPolicy(helperImage, dispatch, resources, signal) {
+    async initializeEgressPolicy(helperImage, dispatch, resources, labels, signal) {
         if (dispatch.sandbox.networkPolicy.mode !== "public_allowlist")
             return;
         const script = "let s='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>require('fs').writeFileSync('/policy/forge.conf',s,{mode:0o444}))";
         await requireSandboxProcess({
             command: this.config.dockerExecutable,
-            args: this.dockerArgs(["run", "--rm", "--interactive", "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.egressConfigVolume}:/policy`, helperImage, "-e", script]),
+            args: this.dockerArgs(["run", "--rm", "--interactive", ...labelArgs(labels), "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--memory", "128m", "--memory-swap", "128m", "--cpus", "0.25", "--log-driver", "none", "--user", "0", "--entrypoint", "node", "--volume", `${resources.egressConfigVolume}:/policy`, helperImage, "-e", script]),
             input: egressProxyConfig(dispatch.sandbox.networkPolicy.allowedHosts),
             timeoutMs: 60_000,
             maxOutputBytes: 64 * 1024,
@@ -919,6 +1059,51 @@ export class DockerSandboxRuntime {
             }
         }
     }
+    async inspectImageMetadata(tag) {
+        const result = await this.docker(["image", "inspect", tag], 15_000, undefined, 1024 * 1024).catch(() => null);
+        if (!result)
+            return null;
+        const document = JSON.parse(result.stdout);
+        const image = document[0];
+        if (!image || typeof image.Id !== "string" || !/^sha256:[0-9a-f]{64}$/i.test(image.Id))
+            return null;
+        const labels = image.Config?.Labels;
+        return {
+            id: image.Id,
+            labels: labels && typeof labels === "object" && !Array.isArray(labels)
+                ? Object.fromEntries(Object.entries(labels).filter((entry) => typeof entry[1] === "string"))
+                : {}
+        };
+    }
+    startPeakMemorySampler(containers) {
+        const intervalMs = this.config.sandboxMemorySampleIntervalMs;
+        const controller = new AbortController();
+        const accumulator = createSandboxMemoryAccumulator(intervalMs);
+        const done = (async () => {
+            while (!controller.signal.aborted) {
+                try {
+                    const result = await this.docker(["stats", "--no-stream", "--format", "{{json .}}", ...containers.map(container => container.id)], Math.max(5_000, intervalMs * 3), controller.signal, 128 * 1024);
+                    const sample = parseDockerStatsMemorySample(result.stdout);
+                    if (sample.length === 0)
+                        accumulator.failedSampleCount += 1;
+                    else
+                        recordSandboxMemorySample(accumulator, containers, sample, new Date().toISOString());
+                }
+                catch {
+                    if (!controller.signal.aborted)
+                        accumulator.failedSampleCount += 1;
+                }
+                await waitForMemorySampleInterval(intervalMs, controller.signal);
+            }
+        })();
+        return {
+            stop: async () => {
+                controller.abort("sandbox memory sampling complete");
+                await done.catch(() => undefined);
+                return finalizeSandboxMemoryTelemetry(accumulator);
+            }
+        };
+    }
     docker(args, timeoutMs, signal, maxOutputBytes = 1024 * 1024) {
         return requireSandboxProcess({ command: this.config.dockerExecutable, args: this.dockerArgs(args), timeoutMs, maxOutputBytes, signal });
     }
@@ -939,9 +1124,7 @@ class HostGit {
     async prepareLocked(dispatch, attemptRoot) {
         const baseBranch = dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase || dispatch.repo.defaultBranch;
         await this.git(["fetch", "--prune", "origin"], 5 * 60_000).catch(() => null);
-        const worktreeRef = `refs/heads/${dispatch.lease.worktreeKey}`;
-        const baseCandidates = [worktreeRef, `refs/remotes/origin/${baseBranch}`, `refs/heads/${baseBranch}`];
-        const inputCommitSha = await this.resolveFirst(baseCandidates);
+        const inputCommitSha = await this.resolveFirst([...selectSandboxInputRefs(dispatch.lease.worktreeKey, baseBranch)]);
         const configSelection = selectSandboxConfigRefs(dispatch.sandbox.executionPolicy, dispatch.sandbox.sandboxConfigCommitSha, dispatch.repo.defaultBranch);
         const configCommitSha = await this.resolveFirst([...configSelection.refs]);
         const approvedConfigSha = configSelection.approvedSha;
@@ -1048,7 +1231,8 @@ class HostGit {
         const listing = (await this.git(["worktree", "list", "--porcelain"], 30_000)).stdout;
         const checkedOut = parseWorktreeListing(listing).find(entry => entry.branch === branchRef);
         if (!checkedOut) {
-            await this.git(["update-ref", branchRef, imported, expected], 30_000);
+            const current = (await this.git(["for-each-ref", "--format=%(objectname)", branchRef], 30_000)).stdout.trim();
+            await this.git(["update-ref", branchRef, imported, managedBranchUpdateExpectedValue(current, expected, imported)], 30_000);
             return;
         }
         const head = (await requireSandboxProcess({ command: "git", args: ["-C", checkedOut.path, "rev-parse", "HEAD"], timeoutMs: 30_000 })).stdout.trim();
@@ -1069,6 +1253,16 @@ class HostGit {
     }
     git(args, timeoutMs, signal, env) { return requireSandboxProcess({ command: "git", args: ["-C", this.repoPath, ...args], timeoutMs, maxOutputBytes: 4 * 1024 * 1024, signal, env }); }
 }
+export function managedBranchUpdateExpectedValue(current, expectedInput, imported) {
+    const normalized = current.trim();
+    if (!normalized) {
+        return "0".repeat(imported.length);
+    }
+    if (normalized !== expectedInput) {
+        throw new Error("sandbox_output_conflict: managed branch changed after sandbox input was captured.");
+    }
+    return normalized;
+}
 export function publicationPushArgs(branch, resultCommitSha, inputCommitSha, remoteCommitSha, remote = "origin") {
     const isCommit = (value) => /^[0-9a-f]{40,64}$/iu.test(value);
     if (!branch || branch.length > 240 || !isCommit(resultCommitSha) || !isCommit(inputCommitSha) || (remoteCommitSha && !isCommit(remoteCommitSha))) {
@@ -1188,11 +1382,18 @@ export function selectSandboxConfigRefs(executionPolicy, configuredSha, defaultB
     }
     return approvedSha
         ? { refs: [approvedSha], approvedSha }
-        : { refs: [`refs/remotes/origin/${defaultBranch}`, `refs/heads/${defaultBranch}`], approvedSha: null };
+        : { refs: [`refs/heads/${defaultBranch}`, `refs/remotes/origin/${defaultBranch}`], approvedSha: null };
+}
+export function selectSandboxInputRefs(worktreeKey, baseBranch) {
+    return [
+        `refs/heads/${worktreeKey}`,
+        `refs/heads/${baseBranch}`,
+        `refs/remotes/origin/${baseBranch}`
+    ];
 }
 export function sandboxTimeLimits(environment = process.env) {
     const hardWallSeconds = boundedInteger(environment.FORGE_SANDBOX_HARD_WALL_SECONDS, 8 * 60 * 60, 60, 8 * 60 * 60);
-    const idleSeconds = boundedInteger(environment.FORGE_SANDBOX_IDLE_SECONDS, 30 * 60, 60, hardWallSeconds);
+    const idleSeconds = boundedInteger(environment.FORGE_SANDBOX_IDLE_SECONDS, 10 * 60, 60, hardWallSeconds);
     return { hardWallMs: hardWallSeconds * 1000, idleMs: idleSeconds * 1000 };
 }
 function boundedInteger(value, fallback, minimum, maximum) {
@@ -1220,7 +1421,12 @@ function parseWorktreeListing(value) {
 async function validateOutput(attemptRoot, dispatch) {
     const outputRoot = path.join(attemptRoot, "output");
     const manifestPath = path.join(outputRoot, "manifest.json");
-    const stat = await fs.lstat(manifestPath);
+    const stat = await fs.lstat(manifestPath).catch(error => {
+        if (isNodeErrorWithCode(error, "ENOENT")) {
+            throw new Error("sandbox_output_missing: sandbox worker did not produce manifest.json.");
+        }
+        throw error;
+    });
     if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
         throw new Error("sandbox_output_invalid: manifest must be a bounded regular file.");
     const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
@@ -1254,6 +1460,22 @@ async function validateManifestFile(root, file, max) {
         throw new Error("sandbox_output_invalid: output hash mismatch.");
     return target;
 }
+function isMissingSandboxManifest(error) {
+    return error instanceof Error && error.message.startsWith("sandbox_output_missing:");
+}
+function isNodeErrorWithCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+export function sandboxWorkerFailureMessage(exitCode, stderr, containerError) {
+    const diagnostic = [containerError, stderr]
+        .filter((value) => Boolean(value?.trim()))
+        .join(" ")
+        .replace(/[\r\n\t]+/gu, " ")
+        .trim()
+        .slice(0, 1000);
+    const suffix = diagnostic ? ` Worker diagnostic: ${diagnostic}` : " No worker diagnostic was captured.";
+    return `sandbox_worker_failed: Sandbox worker exited with code ${exitCode} before producing its output manifest.${suffix}`;
+}
 function identityFor(dispatch) {
     const value = dispatch.sandbox?.dispatchAttemptId.replace(/-/g, "").toLowerCase() ?? "";
     if (!/^[0-9a-f]{32}$/.test(value))
@@ -1321,6 +1543,145 @@ function hasControlCharacters(value) {
         return code < 32 || code === 127;
     });
 }
+function createSandboxMemoryAccumulator(sampleIntervalMs) {
+    return {
+        sampleIntervalMs,
+        sampleCount: 0,
+        failedSampleCount: 0,
+        peakMemoryBytes: 0,
+        firstSampledAt: null,
+        lastSampledAt: null,
+        containerPeaks: new Map()
+    };
+}
+export function parseDockerMemoryBytes(value) {
+    const match = /^([0-9]+(?:\.[0-9]+)?)\s*([kmgt]?i?b)$/iu.exec(value.trim());
+    if (!match)
+        return null;
+    const amount = Number(match[1]);
+    const multipliers = {
+        b: 1,
+        kb: 1000,
+        mb: 1000 ** 2,
+        gb: 1000 ** 3,
+        tb: 1000 ** 4,
+        kib: 1024,
+        mib: 1024 ** 2,
+        gib: 1024 ** 3,
+        tib: 1024 ** 4
+    };
+    const multiplier = multipliers[match[2].toLowerCase()];
+    const bytes = amount * multiplier;
+    return Number.isFinite(bytes) && bytes >= 0 && bytes <= Number.MAX_SAFE_INTEGER
+        ? Math.round(bytes)
+        : null;
+}
+export function parseDockerStatsMemorySample(output) {
+    const samples = [];
+    for (const line of output.split(/\r?\n/u).map(value => value.trim()).filter(Boolean)) {
+        try {
+            const value = JSON.parse(line);
+            const containerId = typeof value.ID === "string" ? value.ID.trim().toLowerCase() : "";
+            const name = typeof value.Name === "string" ? value.Name.trim()
+                : typeof value.Container === "string" ? value.Container.trim()
+                    : "";
+            const usage = typeof value.MemUsage === "string" ? value.MemUsage.split("/", 1)[0]?.trim() ?? "" : "";
+            const memoryBytes = parseDockerMemoryBytes(usage);
+            if ((!containerId && !name) || memoryBytes == null)
+                continue;
+            samples.push({ containerId, name, memoryBytes });
+        }
+        catch {
+            // A malformed line is ignored; the sampler records the round as failed only if no valid rows remain.
+        }
+    }
+    return samples;
+}
+function recordSandboxMemorySample(accumulator, containers, sample, sampledAt) {
+    let aggregateMemoryBytes = 0;
+    let matched = 0;
+    for (const container of containers) {
+        const row = sample.find(candidate => candidate.name === container.name
+            || (candidate.containerId.length > 0 && (container.id.startsWith(candidate.containerId) || candidate.containerId.startsWith(container.id))));
+        if (!row)
+            continue;
+        matched += 1;
+        aggregateMemoryBytes += row.memoryBytes;
+        const previous = accumulator.containerPeaks.get(container.id);
+        if (!previous || row.memoryBytes > previous.peakMemoryBytes) {
+            accumulator.containerPeaks.set(container.id, {
+                containerId: container.id,
+                name: container.name,
+                role: container.role,
+                peakMemoryBytes: row.memoryBytes
+            });
+        }
+    }
+    if (matched === 0) {
+        accumulator.failedSampleCount += 1;
+        return;
+    }
+    accumulator.sampleCount += 1;
+    accumulator.peakMemoryBytes = Math.max(accumulator.peakMemoryBytes, aggregateMemoryBytes);
+    accumulator.firstSampledAt ??= sampledAt;
+    accumulator.lastSampledAt = sampledAt;
+}
+function finalizeSandboxMemoryTelemetry(accumulator) {
+    if (accumulator.sampleCount === 0 || !accumulator.firstSampledAt || !accumulator.lastSampledAt)
+        return null;
+    return {
+        schemaVersion: 1,
+        source: "docker_stats_sampled",
+        sampleIntervalMs: accumulator.sampleIntervalMs,
+        sampleCount: accumulator.sampleCount,
+        failedSampleCount: accumulator.failedSampleCount,
+        peakMemoryBytes: accumulator.peakMemoryBytes,
+        firstSampledAt: accumulator.firstSampledAt,
+        lastSampledAt: accumulator.lastSampledAt,
+        containers: [...accumulator.containerPeaks.values()].sort((left, right) => left.role.localeCompare(right.role) || left.name.localeCompare(right.name))
+    };
+}
+function validSandboxPeakMemoryTelemetry(value) {
+    return value?.schemaVersion === 1
+        && value.source === "docker_stats_sampled"
+        && Number.isInteger(value.sampleIntervalMs) && value.sampleIntervalMs >= 250 && value.sampleIntervalMs <= 30_000
+        && Number.isInteger(value.sampleCount) && value.sampleCount > 0
+        && Number.isInteger(value.failedSampleCount) && value.failedSampleCount >= 0
+        && Number.isSafeInteger(value.peakMemoryBytes) && value.peakMemoryBytes >= 0
+        && typeof value.firstSampledAt === "string" && Number.isFinite(Date.parse(value.firstSampledAt))
+        && typeof value.lastSampledAt === "string" && Number.isFinite(Date.parse(value.lastSampledAt))
+        && Array.isArray(value.containers) && value.containers.length <= 32
+        && value.containers.every(container => typeof container.containerId === "string" && /^[0-9a-f]{12,64}$/iu.test(container.containerId)
+            && typeof container.name === "string" && container.name.length > 0 && container.name.length <= 255 && !hasControlCharacters(container.name)
+            && typeof container.role === "string" && container.role.length > 0 && container.role.length <= 255 && !hasControlCharacters(container.role)
+            && Number.isSafeInteger(container.peakMemoryBytes) && container.peakMemoryBytes >= 0);
+}
+function waitForMemorySampleInterval(intervalMs, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        const complete = () => {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", complete);
+            resolve();
+        };
+        const timeout = setTimeout(complete, intervalMs);
+        timeout.unref?.();
+        signal.addEventListener("abort", complete, { once: true });
+    });
+}
+function formatMemoryBytes(value) {
+    if (value >= 1024 ** 3)
+        return `${(value / 1024 ** 3).toFixed(2)} GiB`;
+    if (value >= 1024 ** 2)
+        return `${(value / 1024 ** 2).toFixed(1)} MiB`;
+    if (value >= 1024)
+        return `${(value / 1024).toFixed(1)} KiB`;
+    return `${value} B`;
+}
+function appendRunOnceEvent(result, dispatchEvent) {
+    return dispatchEvent ? { ...result, events: [...result.events, dispatchEvent] } : result;
+}
 export function assertSandboxImportCurrent(expected, current, signal, nowMs = Date.now()) {
     if (signal.aborted
         || !current
@@ -1330,16 +1691,89 @@ export function assertSandboxImportCurrent(expected, current, signal, nowMs = Da
         throw new Error("sandbox_output_stale: output cannot move the managed ref because its attempt, fence, or lease is no longer current.");
     }
 }
-function validLedger(value) {
-    return value?.schemaVersion === 1
-        && /^[0-9a-f-]{32,36}$/i.test(value.dispatchAttemptId)
-        && typeof value.fencingToken === "string"
-        && typeof value.runnerInstanceId === "string"
-        && Number.isFinite(Date.parse(value.expiresAt))
-        && typeof value.resources?.network === "string"
-        && value.labels?.["dev.forge.dispatch-attempt-id"] === value.dispatchAttemptId
-        && value.labels?.["dev.forge.fencing-token"] === value.fencingToken
-        && value.labels?.["dev.forge.runner-instance-id"] === value.runnerInstanceId;
+export function validSandboxLedger(value) {
+    return normalizeSandboxLedger(value) !== null;
+}
+export function normalizeSandboxLedger(value) {
+    if (validCurrentSandboxLedger(value))
+        return value;
+    if (!validLegacySandboxLedger(value))
+        return null;
+    // Schema v2 did not retain the reservation timestamp. Use the earlier of
+    // its expiry and migration time so an old-instance ledger can transition
+    // immediately during startup reaping, even when its lease has not expired.
+    const createdAt = new Date(Math.min(Date.parse(value.expiresAt), Date.now())).toISOString();
+    let runtimeLease = createRuntimeIsolationLease({
+        leaseId: value.resourceLeaseId,
+        dispatchAttemptId: value.dispatchAttemptId,
+        executionLeaseId: value.resourceLeaseId,
+        fencingToken: value.fencingToken,
+        runnerId: value.labels["dev.forge.runner-id"],
+        runnerInstanceId: value.runnerInstanceId,
+        worktreeKey: `legacy/${value.dispatchAttemptId}`,
+        worktreePath: "/workspace",
+        mode: "docker",
+        createdAt,
+        expiresAt: value.expiresAt,
+        resources: {
+            memoryReservationBytes: 0,
+            cpuMillis: 0,
+            pids: 0,
+            ports: [],
+            paths: [{ path: "/workspace", role: "worktree" }],
+            processSupervisorId: null,
+            dockerResources: plannedDockerLeaseResources(value.resources, true, value.includeCredentials !== false),
+            singletonKeys: [],
+        },
+    });
+    runtimeLease = transitionRuntimeIsolationLease(runtimeLease, "starting", createdAt);
+    runtimeLease = transitionRuntimeIsolationLease(runtimeLease, "active", createdAt);
+    return {
+        schemaVersion: 3,
+        runtimeLease,
+        resources: value.resources,
+        labels: value.labels,
+        includeCredentials: value.includeCredentials,
+        peakMemory: value.peakMemory,
+    };
+}
+function validCurrentSandboxLedger(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const ledger = value;
+    const lease = ledger.runtimeLease;
+    return ledger.schemaVersion === 3
+        && validRuntimeIsolationLease(lease)
+        && lease.mode === "docker"
+        && typeof ledger.resources?.network === "string"
+        && ledger.labels?.["dev.forge.managed"] === "true"
+        && ledger.labels?.["dev.forge.runner-id"] === lease.runnerId
+        && ledger.labels?.["dev.forge.resource-lease-id"] === lease.leaseId
+        && ledger.labels?.["dev.forge.execution-lease-id"] === lease.executionLeaseId
+        && ledger.labels?.["dev.forge.dispatch-attempt-id"] === lease.dispatchAttemptId
+        && ledger.labels?.["dev.forge.fencing-token"] === lease.fencingToken
+        && ledger.labels?.["dev.forge.runner-instance-id"] === lease.runnerInstanceId
+        && (ledger.peakMemory == null || validSandboxPeakMemoryTelemetry(ledger.peakMemory));
+}
+function validLegacySandboxLedger(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const ledger = value;
+    return ledger.schemaVersion === 2
+        && isFullUuid(ledger.resourceLeaseId)
+        && isFullUuid(ledger.dispatchAttemptId)
+        && isFullUuid(ledger.fencingToken)
+        && isFullUuid(ledger.runnerInstanceId)
+        && Number.isFinite(Date.parse(ledger.expiresAt))
+        && typeof ledger.resources?.network === "string"
+        && ledger.labels?.["dev.forge.managed"] === "true"
+        && isFullUuid(ledger.labels?.["dev.forge.runner-id"])
+        && ledger.labels?.["dev.forge.resource-lease-id"] === ledger.resourceLeaseId
+        && ledger.labels?.["dev.forge.execution-lease-id"] === ledger.resourceLeaseId
+        && ledger.labels?.["dev.forge.dispatch-attempt-id"] === ledger.dispatchAttemptId
+        && ledger.labels?.["dev.forge.fencing-token"] === ledger.fencingToken
+        && ledger.labels?.["dev.forge.runner-instance-id"] === ledger.runnerInstanceId
+        && (ledger.peakMemory == null || validSandboxPeakMemoryTelemetry(ledger.peakMemory));
 }
 export function resourceNames(attemptHex, perAttemptCaches = []) { const prefix = `forge-${attemptHex}`; return { prefix, container: `forge-agent-${attemptHex}`, network: prefix, egressNetwork: `${prefix}-egress`, workspaceVolume: `${prefix}-workspace`, controlVolume: `${prefix}-control`, secretsVolume: `${prefix}-secrets`, credentialsVolume: `${prefix}-credentials`, egressConfigVolume: `${prefix}-egress-policy`, cacheVolumes: Object.fromEntries(perAttemptCaches.map(name => [name, `${prefix}-cache-${name}`])) }; }
 export function dockerObjectId(output, kind) {
@@ -1364,9 +1798,41 @@ export function sandboxRuntimeCleanupVolumeNames(resources, includeCredentials =
         .map(volume => volume.name)
         .filter((name) => typeof name === "string" && name.length > 0);
 }
-function labelsFor(dispatch, image, contract) {
+function plannedDockerLeaseResources(resources, includeEgressPolicy, includeCredentials) {
+    return [
+        { type: "container", name: resources.container, role: "agent" },
+        { type: "network", name: resources.network, role: "internal" },
+        ...(includeEgressPolicy ? [{ type: "network", name: resources.egressNetwork, role: "egress" }] : []),
+        ...sandboxRuntimeVolumes(resources, includeEgressPolicy, includeCredentials)
+            .map(volume => ({ type: "volume", name: volume.name, role: volume.role })),
+    ];
+}
+function activeDockerLeaseResources(containers, networks, volumes) {
+    return [
+        ...containers.map(resource => ({ type: "container", ...resource })),
+        ...networks.map(resource => ({ type: "network", ...resource })),
+        ...volumes.map(resource => ({ type: "volume", ...resource })),
+    ];
+}
+function transitionForCleanup(lease, state) {
+    if (lease.state === state)
+        return lease;
+    return transitionRuntimeIsolationLease(lease, state);
+}
+export function sandboxResourceLabels(dispatch, image, contract) {
+    const resourceLeaseId = dispatch.sandbox.executionLeaseId;
+    const ownershipIds = [
+        ["resource lease", resourceLeaseId],
+        ["dispatch attempt", dispatch.sandbox.dispatchAttemptId],
+        ["runner", dispatch.execution.runnerId],
+        ["runner instance", dispatch.sandbox.runnerInstanceId],
+        ["fencing token", dispatch.lease.fencingToken]
+    ];
+    const invalid = ownershipIds.find(([, value]) => !isFullUuid(value));
+    if (invalid)
+        throw new Error(`sandbox_identity_invalid: ${invalid[0]} id must be a full UUID.`);
     return {
-        "dev.forge.managed": "true", "dev.forge.session-id": dispatch.session.id, "dev.forge.execution-lease-id": dispatch.sandbox.executionLeaseId,
+        "dev.forge.managed": "true", "dev.forge.session-id": dispatch.session.id, "dev.forge.resource-lease-id": resourceLeaseId, "dev.forge.execution-lease-id": resourceLeaseId,
         "dev.forge.dispatch-attempt-id": dispatch.sandbox.dispatchAttemptId, "dev.forge.fencing-token": dispatch.lease.fencingToken,
         "dev.forge.runner-id": dispatch.execution.runnerId ?? "", "dev.forge.runner-instance-id": dispatch.sandbox.runnerInstanceId,
         "dev.forge.project": dispatch.repo.name.slice(0, 120), "dev.forge.image-digest": image, "dev.forge.contract-digest": contract,
@@ -1377,31 +1843,47 @@ function labelArgs(labels) { return Object.entries(labels).flatMap(([key, value]
 function labelsMatch(actual, expected) { return Object.entries(expected).every(([key, value]) => actual[key] === value); }
 export function mayReapManagedResource(labels, runnerId, liveAttempts) {
     const attemptId = labels["dev.forge.dispatch-attempt-id"];
+    const resourceLeaseId = labels["dev.forge.resource-lease-id"];
     return labels["dev.forge.managed"] === "true"
         && labels["dev.forge.runner-id"] === runnerId
-        && Boolean(attemptId)
+        && isFullUuid(resourceLeaseId)
+        && labels["dev.forge.execution-lease-id"] === resourceLeaseId
+        && isFullUuid(attemptId)
+        && isFullUuid(labels["dev.forge.runner-instance-id"])
+        && isFullUuid(labels["dev.forge.fencing-token"])
         && !liveAttempts.has(attemptId);
 }
+function isFullUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu.test(value);
+}
 export function shouldReapSandboxLedger(ledger, currentRunnerInstanceId, serverAttempt, snapshotAvailable, nowMs = Date.now()) {
-    if (ledger.runnerInstanceId !== currentRunnerInstanceId)
+    const lease = "runtimeLease" in ledger ? ledger.runtimeLease : ledger;
+    if (lease.runnerInstanceId !== currentRunnerInstanceId)
         return true;
     if (!snapshotAvailable)
-        return Date.parse(ledger.expiresAt) <= nowMs;
+        return Date.parse(lease.expiresAt) <= nowMs;
     return !serverAttempt
-        || serverAttempt.dispatchAttemptId !== ledger.dispatchAttemptId
-        || serverAttempt.fencingToken !== ledger.fencingToken
-        || serverAttempt.runnerInstanceId !== ledger.runnerInstanceId
+        || serverAttempt.dispatchAttemptId !== lease.dispatchAttemptId
+        || serverAttempt.fencingToken !== lease.fencingToken
+        || serverAttempt.runnerInstanceId !== lease.runnerInstanceId
         || Date.parse(serverAttempt.expiresAt) <= nowMs;
 }
 function dockerLabelValue(value) { return value.replace(/[\r\n\0]/gu, " ").trim().slice(0, 120) || "unknown"; }
-function imageLabelArgs(project, key, kind) {
+function imageLabelArgs(project, key, kind, bridgeRuntimeDigest) {
     return [
         "--label", managedLabel,
         "--label", `dev.forge.project=${dockerLabelValue(project)}`,
         "--label", `dev.forge.image-key=${key}`,
-        "--label", `dev.forge.image-kind=${kind}`
+        "--label", `dev.forge.image-kind=${kind}`,
+        "--label", `${bridgeRuntimeDigestLabel}=${bridgeRuntimeDigest}`
     ];
 }
+export function bridgeRuntimeCacheMatches(record, expectedDigest, imageLabels) {
+    return /^[0-9a-f]{64}$/i.test(expectedDigest)
+        && record?.bridgeRuntimeDigest === expectedDigest
+        && imageLabels.length > 0
+        && imageLabels.every(labels => labels?.[bridgeRuntimeDigestLabel] === expectedDigest);
+}
 function validImageCacheRecord(value) {
     return value?.schemaVersion === 1
         && /^[0-9a-f]{64}$/i.test(value.key)
@@ -1411,25 +1893,213 @@ function validImageCacheRecord(value) {
         && [value.projectTag, value.helperTag, value.overlayTag].every(tag => /^forge\/(?:project|tooling|agent):[0-9a-f]{64}$/i.test(tag))
         && /^sha256:[0-9a-f]{64}$/i.test(value.imageDigest)
         && /^sha256:[0-9a-f]{64}$/i.test(value.helperImageDigest)
+        && (value.bridgeRuntimeDigest === undefined || /^[0-9a-f]{64}$/i.test(value.bridgeRuntimeDigest))
         && /^[0-9a-f]{64}$/i.test(value.policyDigest);
 }
-export function buildxBuildArgs(builder, metadataFile, tail, environment = process.env) {
+export async function prepareOverlayBuildRoot(overlayRoot) {
+    const buildRoot = path.dirname(overlayRoot);
+    await fs.mkdir(buildRoot, { recursive: true, mode: 0o700 });
+    await fs.chmod(buildRoot, 0o700);
+    await fs.rm(overlayRoot, { recursive: true, force: true });
+    await fs.mkdir(overlayRoot, { recursive: true, mode: 0o700 });
+    await fs.chmod(overlayRoot, 0o700);
+    const bridgeRoot = path.join(overlayRoot, "bridge");
+    await fs.mkdir(bridgeRoot, { recursive: true, mode: 0o700 });
+    await fs.chmod(bridgeRoot, 0o700);
+}
+export async function extractOciLayoutArchive(archivePath, destination, signal) {
+    await fs.rm(destination, { recursive: true, force: true });
+    await fs.mkdir(destination, { recursive: true, mode: 0o700 });
+    await fs.chmod(destination, 0o700);
+    const result = await runSandboxProcess({
+        command: process.platform === "win32" ? "tar.exe" : "tar",
+        args: ["-xf", archivePath, "-C", destination],
+        timeoutMs: 5 * 60_000,
+        maxOutputBytes: 1024 * 1024,
+        signal
+    });
+    if (result.exitCode !== 0 || result.truncated) {
+        throw new Error(`sandbox_build_failed: project OCI layout extraction failed with exit code ${result.exitCode}; ${formatOciExtractionFailure(result)}. Archive retained at ${archivePath}.`);
+    }
+    await fs.rm(archivePath, { force: true }).catch(() => undefined);
+}
+export function ociLayoutContextRef(layoutPath) {
+    if (/^[A-Za-z]:[\\/]/u.test(layoutPath)) {
+        throw new Error("sandbox_build_failed: Windows absolute OCI layout paths are not BuildKit-safe; use a relative path from the build working directory.");
+    }
+    const normalized = layoutPath.replace(/\\/gu, "/").replace(/^\.\//u, "");
+    // BuildKit's oci-layout resolver expects a raw filesystem path here; it does not percent-decode
+    // URI path escapes such as %20 before opening index.json. On Windows, absolute drive paths
+    // such as D:/state/project-oci are parsed as OCI layout ref/tag syntax, so callers should
+    // run buildx from the layout parent and pass a relative path (for example project-oci).
+    return `oci-layout://${normalized}`;
+}
+export function formatOciExtractionFailure(result) {
+    const output = result.stderr.trim() || result.stdout.trim() || "no tar output";
+    return `tar output: ${output.slice(0, 2048)}${result.truncated ? " (output truncated)" : ""}`;
+}
+export async function readOciLayoutImageDigest(layoutRoot) {
+    const indexPath = path.join(layoutRoot, "index.json");
+    const index = JSON.parse(await fs.readFile(indexPath, "utf8"));
+    const manifest = index.manifests?.find(entry => typeof entry.digest === "string"
+        && /^sha256:[0-9a-f]{64}$/iu.test(entry.digest)
+        && entry.annotations?.["vnd.docker.reference.type"] !== "attestation-manifest");
+    if (!manifest || typeof manifest.digest !== "string") {
+        throw new Error("sandbox_build_failed: project OCI layout did not expose an immutable image digest.");
+    }
+    return manifest.digest;
+}
+export async function removeExtractedOciLayout(layoutRoot) {
+    await fs.rm(layoutRoot, { recursive: true, force: true });
+}
+export function ociLayoutScanTarget(layoutPath) {
+    const absolute = /^[A-Za-z]:[\\/]/u.test(layoutPath) ? layoutPath : path.resolve(layoutPath);
+    return `oci-dir:${absolute.replace(/\\/gu, "/")}`;
+}
+export function agentOverlayDockerignore() {
+    return "project.oci.tar\nproject-oci\nproject-oci/**\n";
+}
+export function sandboxImageCacheKey(input) {
+    return createHash("sha256").update([
+        input.contextDigest,
+        input.contractDigest,
+        input.platform,
+        input.architecture,
+        input.bridgeVersion,
+        input.bridgeRuntimeDigest,
+        input.toolingImage,
+        input.codexVersion,
+        input.policy,
+        input.policyConfigurationDigest
+    ].join("\0")).digest("hex");
+}
+export async function bridgeRuntimeContentDigest(packageRoot) {
+    const root = path.resolve(packageRoot);
+    const packageManifest = await requireBridgeRuntimeFile(root, "package.json");
+    const lockManifest = await optionalBridgeRuntimeFile(root, "package-lock.json");
+    const distRoot = path.join(root, "dist");
+    const distStat = await fs.lstat(distRoot).catch(() => null);
+    if (!distStat?.isDirectory() || distStat.isSymbolicLink()) {
+        throw new Error("sandbox_build_failed: bridge runtime dist must be a real directory.");
+    }
+    const distFiles = await collectBridgeRuntimeFiles(root, "dist");
+    if (distFiles.length === 0) {
+        throw new Error("sandbox_build_failed: bridge runtime dist is empty.");
+    }
+    const files = [packageManifest, ...(lockManifest ? [lockManifest] : []), ...distFiles]
+        .sort((left, right) => compareBridgeRuntimePaths(left.relativePath, right.relativePath));
+    const digest = createHash("sha256");
+    digest.update("forge-bridge-runtime-v1\0");
+    digest.update(`${files.length}\0`);
+    for (const file of files) {
+        const contents = await fs.readFile(file.absolutePath);
+        digest.update(`${Buffer.byteLength(file.relativePath, "utf8")}:${file.relativePath}\0`);
+        digest.update(`${contents.length}:`);
+        digest.update(contents);
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+async function requireBridgeRuntimeFile(root, relativePath) {
+    const file = await optionalBridgeRuntimeFile(root, relativePath);
+    if (!file)
+        throw new Error(`sandbox_build_failed: bridge runtime ${relativePath} is missing.`);
+    return file;
+}
+async function optionalBridgeRuntimeFile(root, relativePath) {
+    const absolutePath = path.join(root, relativePath);
+    const stat = await fs.lstat(absolutePath).catch(() => null);
+    if (!stat)
+        return null;
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error(`sandbox_build_failed: bridge runtime ${relativePath} must be a regular file.`);
+    }
+    return { absolutePath, relativePath: relativePath.replace(/\\/gu, "/") };
+}
+async function collectBridgeRuntimeFiles(root, relativeDirectory) {
+    const absoluteDirectory = path.join(root, relativeDirectory);
+    const entries = (await fs.readdir(absoluteDirectory, { withFileTypes: true }))
+        .sort((left, right) => compareBridgeRuntimePaths(left.name, right.name));
+    const files = [];
+    for (const entry of entries) {
+        const relativePath = path.join(relativeDirectory, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`sandbox_build_failed: bridge runtime ${relativePath.replace(/\\/gu, "/")} cannot be a symbolic link.`);
+        }
+        if (entry.isDirectory()) {
+            files.push(...await collectBridgeRuntimeFiles(root, relativePath));
+            continue;
+        }
+        if (!entry.isFile()) {
+            throw new Error(`sandbox_build_failed: bridge runtime ${relativePath.replace(/\\/gu, "/")} must be a regular file.`);
+        }
+        files.push({
+            absolutePath: path.join(root, relativePath),
+            relativePath: relativePath.replace(/\\/gu, "/")
+        });
+    }
+    return files;
+}
+function compareBridgeRuntimePaths(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+export function agentOverlayDockerfile(toolingImage, projectContextName, installMode, codexVersion) {
+    return `FROM ${toolingImage} AS tooling
+WORKDIR /opt/forge-bridge
+COPY bridge/package*.json ./
+RUN ${bridgePackageInstallCommand(installMode, codexVersion)}
+COPY bridge/dist ./dist
+FROM ${projectContextName}
+USER 0
+COPY --from=tooling /usr/local/bin/node /usr/local/bin/node
+COPY --from=tooling /usr/local/lib/node_modules/@openai/codex /usr/local/lib/node_modules/@openai/codex
+COPY --from=tooling /opt/forge-bridge /opt/forge-bridge
+RUN ln -sfn ../lib/node_modules/@openai/codex/bin/codex.js /usr/local/bin/codex \
+    && (getent group 10001 || groupadd -g 10001 forge) \
+    && (getent passwd 10001 || useradd -u 10001 -g 10001 -d /home/forge -m forge)
+ENV HOME=/home/forge TMPDIR=/tmp
+ENTRYPOINT []
+CMD []
+USER 10001:10001
+`;
+}
+export async function copyBridgePackageManifests(packageRoot, bridgeRoot) {
+    await fs.copyFile(path.join(packageRoot, "package.json"), path.join(bridgeRoot, "package.json"));
+    return await copyOptionalBridgeManifest(packageRoot, bridgeRoot, "package-lock.json") ? "ci" : "install";
+}
+export function bridgePackageInstallCommand(mode, codexVersion) {
+    const bridgeInstall = mode === "ci"
+        ? "npm ci --omit=dev --ignore-scripts"
+        : "npm install --omit=dev --ignore-scripts";
+    return `${bridgeInstall} && npm install --global @openai/codex@${codexVersion} && npm cache clean --force`;
+}
+async function copyOptionalBridgeManifest(packageRoot, bridgeRoot, fileName) {
+    try {
+        await fs.copyFile(path.join(packageRoot, fileName), path.join(bridgeRoot, fileName));
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function buildxBuildArgs(builder, metadataFile, tail, environment = process.env, options = {}) {
     if (!/^forge-[0-9a-f]{20}$/u.test(builder))
         throw new Error("sandbox_build_failed: invalid dedicated builder name.");
     const resources = buildResourcePolicy(environment);
-    return [
-        "buildx", "build", "--builder", builder, "--load",
-        "--ulimit", `nofile=${resources.nofile}:${resources.nofile}`,
-        "--shm-size", resources.sharedMemory,
-        "--provenance=mode=max", "--sbom=true", "--metadata-file", metadataFile,
-        ...tail
-    ];
+    const args = ["buildx", "build", "--builder", builder];
+    if (options.load !== false)
+        args.push("--load");
+    args.push("--ulimit", `nofile=${resources.nofile}:${resources.nofile}`, "--shm-size", resources.sharedMemory, "--provenance=mode=max", "--sbom=true", "--metadata-file", metadataFile, ...tail);
+    return args;
 }
 export function buildResourcePolicy(environment = process.env) {
     return {
         nofile: boundedInteger(environment.FORGE_SANDBOX_BUILD_NOFILE, 4_096, 256, 65_536),
         sharedMemory: "256m",
-        builderPidsLimit: boundedInteger(environment.FORGE_SANDBOX_BUILDER_PIDS_LIMIT, 512, 128, 4_096)
+        builderPidsLimit: boundedInteger(environment.FORGE_SANDBOX_BUILDER_PIDS_LIMIT, 512, 128, 4_096),
+        builderMemoryBytes: boundedInteger(environment.FORGE_SANDBOX_BUILDER_MEMORY_BYTES, 3 * 1024 ** 3, 512 * 1024 ** 2, 16 * 1024 ** 3)
     };
 }
 export function dedicatedBuildxBuilderName(runnerId, dockerContext) {
@@ -1469,7 +2139,17 @@ async function sandboxProviderAuthForDispatch(dispatch) {
 }
 export function workerCreateArgs(dispatch, contract, resources, labels, image, securityOptions = resolveSandboxSecurityOptions(dispatch.sandbox.executionPolicy)) {
     const r = dispatch.sandbox.requestedResources;
-    return ["create", "--name", resources.container, ...labelArgs(labels), "--network", resources.network, "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", ...securityOptions, "--pids-limit", String(r.pids), "--memory", String(r.memoryBytes), "--memory-swap", String(r.memoryBytes), "--cpus", String(r.cpuMillis / 1000), "--ulimit", "nofile=4096:4096", "--ulimit", "core=0", "--tmpfs", "/tmp:rw,nosuid,nodev,size=1g,uid=10001,gid=10001", "--tmpfs", "/run/forge:rw,nosuid,nodev,noexec,size=32m,uid=10001,gid=10001", "--user", "10001:10001", "--workdir", contract.contract.workingDirectory, "--init", "--stop-timeout", "10", "--entrypoint", "node", "--log-driver", "none", "--volume", `${resources.workspaceVolume}:/workspace`, "--volume", `${resources.controlVolume}:/control`, "--volume", `${resources.secretsVolume}:/run/forge-secrets:ro`, ...providerAuthVolumeArgs(dispatch, resources), ...cacheVolumeArgs(contract, resources), "--env", `FORGE_SESSION_ID=${dispatch.session.id}`, "--env", `FORGE_DISPATCH_ATTEMPT_ID=${dispatch.sandbox.dispatchAttemptId}`, "--env", `FORGE_EXECUTION_LEASE_ID=${dispatch.sandbox.executionLeaseId}`, "--env", `FORGE_FENCING_TOKEN=${dispatch.lease.fencingToken}`, "--env", `FORGE_SANDBOX_ID=${dispatch.sandbox.dispatchAttemptId}`, "--env", "FORGE_WORKSPACE=/workspace", "--env", `FORGE_INPUT_COMMIT_SHA=${dispatch.sandbox.inputCommitSha}`, "--env", "FORGE_INPUT_BUNDLE=/control/input/repo.bundle", ...proxyEnvironmentArgs(dispatch, contract, resources), "--env", "HOME=/home/forge", "--env", "TMPDIR=/tmp", image, "/opt/forge-bridge/dist/sandbox/worker.js"];
+    return ["create", "--interactive", "--name", resources.container, ...labelArgs(labels), "--network", resources.network, "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", ...securityOptions, "--pids-limit", String(r.pids), "--memory", String(r.workerMemoryLimitBytes), "--memory-swap", String(r.workerMemoryLimitBytes), "--cpus", String(r.cpuMillis / 1000), "--ulimit", "nofile=4096:4096", "--ulimit", "core=0", "--tmpfs", "/tmp:rw,nosuid,nodev,size=1g,uid=10001,gid=10001", "--tmpfs", "/run/forge:rw,nosuid,nodev,noexec,size=32m,uid=10001,gid=10001", "--user", "10001:10001", "--workdir", contract.contract.workingDirectory, "--init", "--stop-timeout", "10", "--entrypoint", "node", "--log-driver", "none", "--mount", `type=volume,src=${resources.workspaceVolume},dst=/workspace,volume-nocopy`, "--volume", `${resources.controlVolume}:/control`, "--volume", `${resources.secretsVolume}:/run/forge-secrets:ro`, ...providerAuthVolumeArgs(dispatch, resources), ...cacheVolumeArgs(contract, resources), "--env", `FORGE_SESSION_ID=${dispatch.session.id}`, "--env", `FORGE_DISPATCH_ATTEMPT_ID=${dispatch.sandbox.dispatchAttemptId}`, "--env", `FORGE_RESOURCE_LEASE_ID=${dispatch.sandbox.executionLeaseId}`, "--env", `FORGE_EXECUTION_LEASE_ID=${dispatch.sandbox.executionLeaseId}`, "--env", `FORGE_FENCING_TOKEN=${dispatch.lease.fencingToken}`, "--env", "FORGE_RUNTIME_MODE=docker", "--env", `FORGE_SANDBOX_ID=${dispatch.sandbox.dispatchAttemptId}`, "--env", "FORGE_WORKSPACE=/workspace", "--env", "FORGE_WORKTREE_PATH=/workspace", "--env", "FORGE_TMPDIR=/tmp", "--env", "FORGE_LOG_DIR=/control/output/logs", "--env", "FORGE_BROWSER_PROFILE_DIR=/tmp/forge-browser-profile", "--env", `FORGE_INPUT_COMMIT_SHA=${dispatch.sandbox.inputCommitSha}`, "--env", "FORGE_INPUT_BUNDLE=/control/input/repo.bundle", ...proxyEnvironmentArgs(dispatch, contract, resources), "--env", "HOME=/home/forge", "--env", "TMPDIR=/tmp", image, "/opt/forge-bridge/dist/sandbox/worker.js"];
+}
+export function validateSandboxMemoryReservation(dispatch, contract) {
+    const requested = dispatch.sandbox.requestedResources;
+    const requiredServiceMemoryBytes = contract.contract.services.length * 1024 ** 3;
+    const requiredRuntimeOverheadBytes = 128 * 1024 ** 2
+        + (dispatch.sandbox.networkPolicy.mode === "public_allowlist" ? 256 * 1024 ** 2 : 0);
+    if (requested.serviceMemoryLimitBytes < requiredServiceMemoryBytes
+        || requested.runtimeOverheadBytes < requiredRuntimeOverheadBytes) {
+        throw new Error(`sandbox_capacity_profile_mismatch: reserved ${requested.serviceMemoryLimitBytes} service bytes and ${requested.runtimeOverheadBytes} runtime overhead bytes; the contract requires at least ${requiredServiceMemoryBytes} service bytes and ${requiredRuntimeOverheadBytes} runtime overhead bytes.`);
+    }
 }
 function providerAuthVolumeArgs(dispatch, resources) {
     const adapter = sandboxProviderAuthAdapterFor(dispatch.execution.provider, dispatch.execution.authKind);
@@ -1485,7 +2165,7 @@ export function cacheVolumeArgs(contract, resources) {
     };
     return contract.contract.caches
         .filter(cache => cache.mode === "per_attempt")
-        .flatMap(cache => ["--volume", `${resources.cacheVolumes[cache.name]}:${targets[cache.name]}`]);
+        .flatMap(cache => ["--mount", `type=volume,src=${resources.cacheVolumes[cache.name]},dst=${targets[cache.name]},volume-nocopy`]);
 }
 export function proxyEnvironmentArgs(dispatch, contract, resources) {
     if (dispatch.sandbox.networkPolicy.mode !== "public_allowlist")
@@ -1554,10 +2234,10 @@ export function resolveSandboxSecurityOptions(executionPolicy, environment = pro
         ...(lsm ? ["--security-opt", lsm] : [])
     ];
 }
-export function networkCreateArgs(dispatch, environment = process.env) {
+export function networkCreateArgs(dispatch, environment = process.env, allowOpenPublicSandbox = environment.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX === "true") {
     const policy = dispatch.sandbox.networkPolicy;
     if (policy.mode === "open_public") {
-        if (dispatch.sandbox.executionPolicy === "sandbox_required" || environment.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX !== "true") {
+        if (dispatch.sandbox.executionPolicy === "sandbox_required" || !allowOpenPublicSandbox) {
             throw new Error("policy_mismatch: open_public sandbox networking is not permitted by this runner policy.");
         }
         return [];