@loucompanion/forge-bridge 0.1.3-dev.bd0c67bbf352 → 0.1.3-dev.c24058d57ab3

package/dist/sandbox/runtime.js

@@ -0,0 +1,1767 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { failureResult } from "../session/session.types.js";
+import { dockerfileUpstreamImages, validateDockerfilePolicy, validateSandboxContract } from "./contract.js";
+import { requireSandboxProcess, runSandboxProcess } from "./process.js";
+import { createLeaseUpdate } from "./lease-watchdog.js";
+import { evaluateSandboxImagePolicy, hasSandboxImagePolicyRecord, sandboxImagePolicyConfigurationDigest, verifySandboxImageSignature } from "./image-policy.js";
+import { SandboxEventBudget } from "./event-budget.js";
+import { RepositoryCoordinatorLock } from "./repository-lock.js";
+import { redactText } from "../shared/redaction/redaction.js";
+import { sandboxProviderAuthAdapterFor, sandboxProviderAuthUnavailableMessage } from "./provider-auth/codex.js";
+const managedLabel = "dev.forge.managed=true";
+export class DockerSandboxRuntime {
+    config;
+    publicationGrantRedeemer;
+    active = new Map();
+    degraded = new Set();
+    builds = new Map();
+    verifiedCatalogImages = new Set();
+    buildTail = Promise.resolve();
+    constructor(config, publicationGrantRedeemer) {
+        this.config = config;
+        this.publicationGrantRedeemer = publicationGrantRedeemer;
+    }
+    async runOnce(dispatch, sink, signal) {
+        if (!dispatch.sandbox || dispatch.sandbox.executionMode !== "docker" || dispatch.sandbox.runtime !== "docker") {
+            throw new Error("Docker runtime requires a protocol-v2 Docker sandbox dispatch.");
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason ?? "sandbox cancelled");
+        signal?.addEventListener("abort", abort, { once: true });
+        const active = {
+            dispatchAttemptId: dispatch.sandbox.dispatchAttemptId,
+            fencingToken: dispatch.lease.fencingToken,
+            expiresAt: dispatch.lease.expiresAt,
+            controller,
+            phase: "starting",
+            ledger: null,
+            leaseControlKey: randomBytes(32).toString("base64url")
+        };
+        this.active.set(active.dispatchAttemptId, active);
+        const watchdog = setInterval(() => {
+            if (Date.parse(active.expiresAt) <= Date.now() && !controller.signal.aborted) {
+                controller.abort("dispatch lease expired");
+            }
+        }, 500);
+        watchdog.unref?.();
+        const runtimeSignal = controller.signal;
+        try {
+            const identity = identityFor(dispatch);
+            const attemptRoot = path.join(this.config.sandboxStateRoot, "attempts", identity.attemptHex);
+            await fs.mkdir(path.join(attemptRoot, "input"), { recursive: true, mode: 0o700 });
+            await fs.mkdir(path.join(attemptRoot, "output"), { recursive: true, mode: 0o700 });
+            const repoPath = dispatch.repo.serverLocalPath ? path.resolve(dispatch.repo.serverLocalPath) : null;
+            if (!repoPath)
+                throw new Error("sandbox_input_failed: bridge repository mapping is required for bundle handoff.");
+            await sink.emit(event("sandbox_preparing", `Preparing Docker sandbox attempt ${dispatch.sandbox.dispatchAttemptId}.`));
+            const git = new HostGit(this.config, repoPath);
+            const prepared = await git.prepare(dispatch, attemptRoot, runtimeSignal);
+            const validated = validateSandboxContract(prepared.contractSource);
+            validateDockerfilePolicy(prepared.dockerfile, dispatch.sandbox.executionPolicy === "sandbox_required");
+            const upstreamImages = dockerfileUpstreamImages(prepared.dockerfile);
+            const securityOptions = resolveSandboxSecurityOptions(dispatch.sandbox.executionPolicy);
+            const builtImage = await this.buildImage(prepared.contextRoot, prepared.contextDigest, dispatch.repo.name, validated, upstreamImages, dispatch.sandbox.executionPolicy, sink, runtimeSignal);
+            const imageDigest = builtImage.imageDigest;
+            const runtimeDispatch = withSandboxMetadata(dispatch, prepared.inputCommitSha, prepared.configCommitSha, validated.digest, imageDigest);
+            const providerAuthAdapter = sandboxProviderAuthAdapterFor(runtimeDispatch.execution.provider, runtimeDispatch.execution.authKind);
+            const providerAuthUnavailable = sandboxProviderAuthUnavailableMessage(runtimeDispatch.execution.provider, runtimeDispatch.execution.authKind);
+            if (providerAuthUnavailable) {
+                throw new Error(`sandbox_auth_unavailable: ${providerAuthUnavailable}`);
+            }
+            await sink.emit(event("sandbox_metadata", "Resolved immutable sandbox inputs.", {
+                inputCommitSha: prepared.inputCommitSha,
+                sandboxConfigCommitSha: prepared.configCommitSha,
+                contractDigest: validated.digest,
+                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);
+            active.ledger = {
+                schemaVersion: 1,
+                dispatchAttemptId: active.dispatchAttemptId,
+                fencingToken: active.fencingToken,
+                runnerInstanceId: this.config.runnerInstanceId,
+                expiresAt: active.expiresAt,
+                resources,
+                labels,
+                includeCredentials: Boolean(providerAuthAdapter)
+            };
+            await this.writeLedger(active.ledger);
+            let teardownComplete = false;
+            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);
+                await this.docker(["volume", "create", ...labelArgs(labels), resources.controlVolume], 30_000, runtimeSignal);
+                await this.docker(["volume", "create", ...labelArgs(labels), resources.secretsVolume], 30_000, runtimeSignal);
+                if (providerAuthAdapter) {
+                    await this.docker(["volume", "create", ...labelArgs(labels), resources.credentialsVolume], 30_000, runtimeSignal);
+                }
+                for (const cacheVolume of Object.values(resources.cacheVolumes)) {
+                    await this.docker(["volume", "create", ...labelArgs(labels), cacheVolume], 30_000, runtimeSignal);
+                }
+                let egressNetworkId = null;
+                if (runtimeDispatch.sandbox.networkPolicy.mode === "public_allowlist") {
+                    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 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);
+                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);
+                await sink.emit(event("sandbox_started", `Docker sandbox ${identity.attemptHex} started.`, {
+                    agentContainer: { id: containerId, name: resources.container, role: "agent" },
+                    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: []
+                }));
+                const eventBudget = new SandboxEventBudget();
+                const start = await runSandboxProcess({
+                    command: this.config.dockerExecutable,
+                    args: this.dockerArgs(["start", "--attach", "--interactive", containerId]),
+                    input: JSON.stringify({
+                        schemaVersion: 1,
+                        dispatch: runtimeDispatch,
+                        leaseControlKey: active.leaseControlKey,
+                        limits: sandboxTimeLimits()
+                    }),
+                    timeoutMs: 8 * 60 * 60 * 1000,
+                    maxOutputBytes: 8 * 1024 * 1024,
+                    terminateOnOutputLimit: true,
+                    signal: runtimeSignal,
+                    onStdoutLine: async (line) => {
+                        eventBudget.accept(line);
+                        const streamedEvent = parseSandboxEventLine(line);
+                        if (streamedEvent) {
+                            if (streamedEvent.eventType === "provider_cli_started")
+                                active.phase = "active";
+                            await sink.emit(streamedEvent);
+                        }
+                    }
+                });
+                if (start.truncated)
+                    throw new Error("sandbox_log_limit: sandbox output exceeded the 8 MiB supervisor capture budget.");
+                const containerState = await this.inspectContainerState(containerId);
+                if (containerState.oomKilled) {
+                    throw new Error("sandbox_oom_killed: Docker terminated the agent after it exceeded the memory limit.");
+                }
+                if (start.exitCode !== 0) {
+                    const resourceFailure = classifySandboxResourceFailure([
+                        containerState.error,
+                        start.stderr,
+                        start.stdout
+                    ].filter(Boolean).join("\n"));
+                    if (resourceFailure)
+                        throw new Error(`${resourceFailure.code}: ${resourceFailure.message}`);
+                }
+                active.phase = "active";
+                await sink.emit(event("sandbox_agent_exited", `Sandbox worker exited with code ${start.exitCode}.`, {
+                    workerExitCode: start.exitCode
+                }));
+                await this.docker(["cp", `${containerId}:/control/output/.`, path.join(attemptRoot, "output")], 60_000);
+                const output = await validateOutput(attemptRoot, runtimeDispatch);
+                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;
+                    if (!handle || !output.manifest.resultCommitSha || !this.publicationGrantRedeemer) {
+                        throw new Error("sandbox_output_publish_forbidden: bridge publication grant redemption is unavailable.");
+                    }
+                    const credential = await this.publicationGrantRedeemer({
+                        dispatchAttemptId: runtimeDispatch.sandbox.dispatchAttemptId,
+                        leaseId: runtimeDispatch.lease.id,
+                        fencingToken: runtimeDispatch.lease.fencingToken,
+                        runnerInstanceId: runtimeDispatch.sandbox.runnerInstanceId,
+                        grantId: handle.grantId,
+                        branch: handle.branch,
+                        resultCommitSha: output.manifest.resultCommitSha
+                    }, runtimeSignal);
+                    validatePublicationCredential(credential);
+                    await git.publishResult(runtimeDispatch, output, () => assertSandboxImportCurrent(active, this.active.get(active.dispatchAttemptId), controller.signal), credential, runtimeSignal);
+                    await sink.emit(event("sandbox_remote_published", "Published the exact fenced result commit from the bridge host.", {
+                        grantId: runtimeDispatch.sandbox.publishGrantHandle.grantId,
+                        branch: runtimeDispatch.sandbox.publishGrantHandle.branch,
+                        resultCommitSha: output.manifest.resultCommitSha
+                    }));
+                }
+                const result = JSON.parse(await fs.readFile(output.resultPath, "utf8"));
+                if (result.exitCode !== 0) {
+                    const resourceFailure = classifySandboxResourceFailure([
+                        result.summary,
+                        ...result.events.flatMap(resultEvent => [resultEvent.eventType, resultEvent.content, resultEvent.data ?? ""])
+                    ].join("\n"));
+                    if (resourceFailure) {
+                        return {
+                            ...result,
+                            summary: resourceFailure.message,
+                            events: [...result.events, event(resourceFailure.code, resourceFailure.message, { phase: "agent" })]
+                        };
+                    }
+                }
+                await sink.emit(event("sandbox_output_imported", "Validated and imported sandbox output.", {
+                    resultCommitSha: output.manifest.resultCommitSha,
+                }));
+                return result;
+            }
+            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 })]);
+            }
+            finally {
+                try {
+                    try {
+                        await sink.emit(event("sandbox_teardown_started", `Removing Docker resources for attempt ${active.dispatchAttemptId}.`)).catch(() => undefined);
+                        const cleanupReport = await this.teardown(resources, labels, "teardown", Boolean(providerAuthAdapter));
+                        await this.persistCleanupReport(cleanupReport);
+                        teardownComplete = true;
+                        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);
+                        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);
+                    }
+                }
+                finally {
+                    if (teardownComplete)
+                        await fs.rm(attemptRoot, { recursive: true, force: true }).catch(() => undefined);
+                }
+            }
+        }
+        finally {
+            clearInterval(watchdog);
+            signal?.removeEventListener("abort", abort);
+            this.active.delete(active.dispatchAttemptId);
+        }
+    }
+    async updateLease(dispatchAttemptId, fencingToken, expiresAt) {
+        if (!Number.isFinite(Date.parse(expiresAt)))
+            return;
+        const active = this.active.get(dispatchAttemptId);
+        if (!active || active.fencingToken !== fencingToken)
+            return;
+        active.expiresAt = expiresAt;
+        if (active.ledger) {
+            active.ledger = { ...active.ledger, expiresAt };
+            await this.writeLedger(active.ledger);
+            await this.pushLeaseUpdate(active).catch(() => undefined);
+        }
+    }
+    async pushLeaseUpdate(active) {
+        if (!active.ledger)
+            return;
+        const update = createLeaseUpdate(active.dispatchAttemptId, active.fencingToken, active.expiresAt, active.leaseControlKey);
+        const script = "let s='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{const f=require('fs'),p='/run/forge/lease-update.json',t=p+'.tmp';f.writeFileSync(t,s,{mode:0o600});f.renameSync(t,p)})";
+        await requireSandboxProcess({
+            command: this.config.dockerExecutable,
+            args: this.dockerArgs(["exec", "--interactive", active.ledger.resources.container, "node", "-e", script]),
+            input: `${JSON.stringify(update)}\n`,
+            timeoutMs: 10_000,
+            maxOutputBytes: 16 * 1024
+        });
+    }
+    snapshot() {
+        let starting = 0;
+        let active = 0;
+        for (const sandbox of this.active.values()) {
+            if (sandbox.phase === "starting")
+                starting += 1;
+            else
+                active += 1;
+        }
+        return { starting, active, degraded: this.degraded.size };
+    }
+    async reap(options = {}) {
+        const liveAttempts = new Set();
+        const snapshotByAttempt = new Map((options.attemptSnapshot ?? []).map(attempt => [attempt.dispatchAttemptId, attempt]));
+        const now = Date.now();
+        for (const attempt of options.attemptSnapshot ?? []) {
+            if (attempt.runnerInstanceId === this.config.runnerInstanceId && Date.parse(attempt.expiresAt) > now) {
+                liveAttempts.add(attempt.dispatchAttemptId);
+            }
+        }
+        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);
+            if (current
+                && current.fencingToken === ledger.fencingToken
+                && ledger.runnerInstanceId === this.config.runnerInstanceId) {
+                liveAttempts.add(ledger.dispatchAttemptId);
+                continue;
+            }
+            const serverAttempt = snapshotByAttempt.get(ledger.dispatchAttemptId);
+            if (!shouldReapSandboxLedger(ledger, this.config.runnerInstanceId, serverAttempt, options.attemptSnapshot !== undefined, now)) {
+                liveAttempts.add(ledger.dispatchAttemptId);
+                continue;
+            }
+            try {
+                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);
+            }
+            catch (error) {
+                if (error instanceof SandboxTeardownError)
+                    await this.persistCleanupReport(error.report);
+                this.degraded.add(ledger.dispatchAttemptId);
+            }
+        }
+        for (const kind of ["container", "network", "volume"]) {
+            for (const id of await this.listResources(kind, "dev.forge.managed=true")) {
+                const labels = await this.inspectResourceLabels(kind, id).catch(() => null);
+                if (!labels || !mayReapManagedResource(labels, this.config.runnerId, liveAttempts))
+                    continue;
+                await this.removeResource(kind, id).catch(() => undefined);
+            }
+        }
+        await this.purgeRestrictedAuditArtifacts();
+        if (options.diskLow) {
+            await this.withBuildPermit(() => this.collectExpiredImages());
+        }
+    }
+    async pendingCleanupReports() {
+        const root = path.join(this.config.sandboxStateRoot, "cleanup-reports");
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const reports = [];
+        for (const entry of (await fs.readdir(root, { withFileTypes: true })).slice(0, 256)) {
+            if (!entry.isFile() || !/^[0-9a-f]{32}\.json$/iu.test(entry.name))
+                continue;
+            const target = path.join(root, entry.name);
+            const stat = await fs.lstat(target);
+            if (stat.isSymbolicLink() || stat.size > 256 * 1024)
+                continue;
+            try {
+                const report = parseCleanupReport(JSON.parse(await fs.readFile(target, "utf8")));
+                if (report)
+                    reports.push(report);
+            }
+            catch {
+                // A corrupt report is retained for operator inspection and never sent as trusted data.
+            }
+        }
+        return reports;
+    }
+    async acknowledgeCleanupReport(reportId) {
+        await fs.rm(this.cleanupReportPath(reportId), { force: true });
+    }
+    async persistCleanupReport(report) {
+        if (report.actions.length === 0)
+            return;
+        const root = path.join(this.config.sandboxStateRoot, "cleanup-reports");
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const target = this.cleanupReportPath(report.reportId);
+        try {
+            await fs.access(target);
+            return;
+        }
+        catch {
+            // The report is new. Write it durably before acknowledging cleanup to the server.
+        }
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        const handle = await fs.open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(report)}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, target);
+    }
+    cleanupReportPath(reportId) {
+        const value = reportId.replace(/-/gu, "").toLowerCase();
+        if (!/^[0-9a-f]{32}$/u.test(value))
+            throw new Error("sandbox_cleanup_report_invalid: report id must be a UUID.");
+        return path.join(this.config.sandboxStateRoot, "cleanup-reports", `${value}.json`);
+    }
+    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 temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        const handle = await fs.open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(ledger)}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, target);
+    }
+    async readLedgers() {
+        const root = path.join(this.config.sandboxStateRoot, "ledger");
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const result = [];
+        for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+            if (!entry.isFile() || !/^[0-9a-f]{32}\.json$/i.test(entry.name))
+                continue;
+            const target = path.join(root, entry.name);
+            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))
+                result.push(ledger);
+        }
+        return result;
+    }
+    ledgerPath(dispatchAttemptId) {
+        const attemptHex = dispatchAttemptId.replace(/-/g, "").toLowerCase();
+        if (!/^[0-9a-f]{32}$/.test(attemptHex))
+            throw new Error("sandbox_identity_invalid: dispatch attempt id must be a full UUID.");
+        return path.join(this.config.sandboxStateRoot, "ledger", `${attemptHex}.json`);
+    }
+    async removeLedger(dispatchAttemptId) {
+        await fs.rm(this.ledgerPath(dispatchAttemptId), { force: true });
+    }
+    async buildImage(contextRoot, contextDigest, project, contract, upstreamImages, policy, sink, signal) {
+        const toolingImage = process.env.FORGE_AGENT_TOOLING_IMAGE ?? "node:22.17.0-bookworm-slim";
+        if (policy === "sandbox_required" && !/@sha256:[0-9a-f]{64}$/i.test(toolingImage)) {
+            throw new Error("sandbox_build_failed: FORGE_AGENT_TOOLING_IMAGE must be digest-pinned for sandbox_required.");
+        }
+        const codexVersion = process.env.FORGE_CODEX_PACKAGE_VERSION ?? "0.144.1";
+        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([
+            contextDigest,
+            contract.digest,
+            process.platform,
+            process.arch,
+            this.config.version,
+            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 }));
+            const waitStartedAt = Date.now();
+            const built = await existing;
+            await sink.emit(event("sandbox_build_singleflight_wait", `Waited for the existing sandbox image build ${key.slice(0, 12)}.`, {
+                durationMs: Date.now() - waitStartedAt,
+                imageDigest: built.imageDigest
+            }));
+            return built;
+        }
+        const promise = this.withBuildPermit(() => this.buildImageCore(contextRoot, contextDigest, contract.digest, key, project, toolingImage, upstreamImages, codexVersion, policy, sink, signal), signal);
+        this.builds.set(key, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.builds.delete(key);
+        }
+    }
+    async withBuildPermit(action, signal) {
+        let release = () => undefined;
+        const turn = new Promise(resolve => { release = resolve; });
+        const previous = this.buildTail;
+        this.buildTail = previous.catch(() => undefined).then(() => turn);
+        await previous.catch(() => undefined);
+        try {
+            if (signal?.aborted)
+                throw new Error(String(signal.reason ?? "sandbox build cancelled"));
+            return await action();
+        }
+        finally {
+            release();
+        }
+    }
+    async buildImageCore(contextRoot, contextDigest, contractDigest, key, project, 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)
+        ]);
+        const cachedHelperDigest = cachedHelper?.stdout.trim() ?? "";
+        const cachedOverlayDigest = cachedOverlay?.stdout.trim() ?? "";
+        const cacheRecordPath = path.join(this.config.sandboxStateRoot, "image-cache", `${key}.json`);
+        const cacheRecord = await this.readImageCacheRecord(cacheRecordPath);
+        const policyRecordValid = cacheRecord?.policyDigest
+            ? await hasSandboxImagePolicyRecord(this.config.sandboxStateRoot, key, cacheRecord.policyDigest, policy === "sandbox_required")
+            : false;
+        if (/^sha256:[0-9a-f]{64}$/i.test(cachedHelperDigest)
+            && /^sha256:[0-9a-f]{64}$/i.test(cachedOverlayDigest)
+            && cacheRecord?.helperImageDigest === cachedHelperDigest
+            && cacheRecord.imageDigest === cachedOverlayDigest
+            && policyRecordValid) {
+            await this.writeImageCacheRecord({
+                ...cacheRecord,
+                lastUsedAt: new Date().toISOString(),
+            });
+            await sink.emit(event("sandbox_image_cache_hit", `Using cached sandbox image ${cachedOverlayDigest}.`, { imageDigest: cachedOverlayDigest }));
+            return { imageDigest: cachedOverlayDigest, helperImageDigest: cachedHelperDigest };
+        }
+        if (cachedHelperDigest || cachedOverlayDigest) {
+            await Promise.all([overlayTag, helperTag, projectTag].map(tag => this.docker(["image", "rm", "--force", tag], 60_000).catch(() => undefined)));
+        }
+        await sink.emit(event("sandbox_image_cache_miss", `Sandbox image ${key.slice(0, 12)} requires a build.`, { cacheKey: key }));
+        if (policy === "sandbox_required" && process.env.FORGE_SANDBOX_BUILD_EGRESS_ENFORCED !== "true") {
+            throw new Error("sandbox_build_policy_failed: sandbox_required builds need an operator-enforced builder egress policy.");
+        }
+        const buildStartedAt = Date.now();
+        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");
+        const overlayRoot = path.join(this.config.sandboxStateRoot, "build", `overlay-${key}`);
+        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"),
+            "--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 packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+        await fs.cp(path.join(packageRoot, "dist"), path.join(overlayRoot, "bridge", "dist"), { recursive: true });
+        const installMode = await copyBridgePackageManifests(packageRoot, path.join(overlayRoot, "bridge"));
+        const dockerfile = agentOverlayDockerfile(toolingImage, projectContextName, installMode, codexVersion);
+        await fs.writeFile(path.join(overlayRoot, "Dockerfile"), dockerfile);
+        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"), "--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",
+            "--build-context", `${projectContextName}=${ociLayoutContextRef(projectOciRoot)}`,
+            ...imageLabelArgs(project, key, "agent"),
+            "--tag", overlayTag,
+            overlayRoot
+        ]), sink, signal);
+        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.");
+        const imagePolicy = await evaluateSandboxImagePolicy({
+            key,
+            project: dockerLabelValue(project),
+            executionPolicy: policy,
+            stateRoot: this.config.sandboxStateRoot,
+            builderVersion: this.config.version,
+            contextDigest,
+            contractDigest,
+            toolingImage,
+            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,
+            project: dockerLabelValue(project),
+            createdAt: new Date().toISOString(),
+            lastUsedAt: new Date().toISOString(),
+            projectTag,
+            helperTag,
+            overlayTag,
+            imageDigest: digest,
+            helperImageDigest,
+            policyDigest: imagePolicy.policyDigest
+        });
+        await sink.emit(event("sandbox_build_completed", `Sandbox image ready at ${digest}.`, {
+            durationMs: Date.now() - buildStartedAt,
+            imageDigest: digest
+        }));
+        return { imageDigest: digest, helperImageDigest };
+    }
+    async runBuildStage(stage, key, args, sink, signal) {
+        const result = await runSandboxProcess({
+            command: this.config.dockerExecutable,
+            args: this.dockerArgs(args),
+            timeoutMs: 30 * 60_000,
+            maxOutputBytes: 2 * 1024 * 1024,
+            terminateOnOutputLimit: true,
+            signal
+        });
+        if (result.exitCode === 0 && !result.truncated)
+            return;
+        const exactSecrets = [this.config.deviceToken, ...Object.entries(process.env)
+                .filter(([name, value]) => /(?:api[_-]?key|authorization|bearer|client[_-]?secret|password|secret|token)/iu.test(name)
+                && typeof value === "string"
+                && value.length >= 8)
+                .map(([, value]) => value)].filter(Boolean);
+        const artifact = restrictedBuildLog(`stage=${stage}\nexitCode=${result.exitCode}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`, exactSecrets);
+        const root = path.join(this.config.sandboxStateRoot, "build-logs", key);
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const target = path.join(root, `${stage}.log`);
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        const handle = await fs.open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(artifact.content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, target);
+        await sink.emit(event("sandbox_build_log_preserved", `Restricted build log retained for failed ${stage} image stage.`, {
+            stage,
+            digest: artifact.digest,
+            byteCount: artifact.byteCount,
+            truncated: artifact.truncated || result.truncated
+        })).catch(() => undefined);
+        throw new Error(`sandbox_build_failed: ${stage} image build failed; restricted log digest ${artifact.digest}.`);
+    }
+    async ensureBuildxBuilder(signal) {
+        const name = dedicatedBuildxBuilderName(this.config.runnerId, this.config.dockerContext);
+        const existing = await this.docker(["buildx", "inspect", name], 30_000, signal).catch(() => null);
+        if (!existing) {
+            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 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.");
+        }
+        return name;
+    }
+    async initializeVolumes(helperImage, resources, 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 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);
+    }
+    async inspectContainerState(containerId) {
+        const result = await this.docker(["container", "inspect", containerId, "--format", "{{json .State}}"], 15_000, undefined, 256 * 1024);
+        const value = JSON.parse(result.stdout);
+        return {
+            oomKilled: value.OOMKilled === true,
+            exitCode: typeof value.ExitCode === "number" ? value.ExitCode : null,
+            error: typeof value.Error === "string" && value.Error.trim() ? value.Error.trim().slice(0, 1000) : null
+        };
+    }
+    async initializeServiceSecrets(helperImage, contract, resources, 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]),
+                input: randomBytes(32).toString("base64url"),
+                timeoutMs: 60_000,
+                maxOutputBytes: 64 * 1024,
+                signal
+            });
+        }
+    }
+    async initializeProviderCredentials(helperImage, dispatch, resources, 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)})";
+        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]),
+            input: JSON.stringify({ files: providerAuth.files }),
+            timeoutMs: 60_000,
+            maxOutputBytes: 64 * 1024,
+            signal
+        });
+    }
+    async initializeEgressPolicy(helperImage, dispatch, resources, 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]),
+            input: egressProxyConfig(dispatch.sandbox.networkPolicy.allowedHosts),
+            timeoutMs: 60_000,
+            maxOutputBytes: 64 * 1024,
+            signal
+        });
+    }
+    async startEgressProxy(dispatch, resources, labels, securityOptions, sink, signal) {
+        if (dispatch.sandbox.networkPolicy.mode !== "public_allowlist")
+            return null;
+        const image = process.env.FORGE_SANDBOX_EGRESS_PROXY_IMAGE?.trim();
+        if (!image || !/@sha256:[0-9a-f]{64}$/iu.test(image)) {
+            throw new Error("sandbox_egress_proxy_unavailable: public_allowlist needs a digest-pinned Squid-compatible proxy image.");
+        }
+        if (process.env.FORGE_SANDBOX_EGRESS_ENFORCED !== "true") {
+            throw new Error("sandbox_egress_proxy_unavailable: runner egress enforcement is not enabled.");
+        }
+        await this.verifyCatalogImage(image, dispatch.sandbox.executionPolicy, sink, signal);
+        const name = `${resources.prefix}-egress`;
+        const containerId = dockerObjectId((await this.docker([
+            "run", "--detach", "--name", name, ...labelArgs(labels), "--network", resources.egressNetwork,
+            "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", ...securityOptions,
+            "--pids-limit", "128", "--memory", "256m", "--memory-swap", "256m", "--cpus", "0.5",
+            "--tmpfs", "/var/spool/squid:rw,nosuid,nodev,noexec,size=128m", "--tmpfs", "/run:rw,nosuid,nodev,noexec,size=16m",
+            "--log-driver", "none", "--volume", `${resources.egressConfigVolume}:/etc/squid/forge:ro`,
+            "--entrypoint", "squid", image, "-N", "-f", "/etc/squid/forge/forge.conf"
+        ], 60_000, signal)).stdout, "container");
+        await this.docker(["network", "connect", "--alias", "forge-egress", resources.network, name], 30_000, signal);
+        return { id: containerId, name, role: "egress_proxy" };
+    }
+    async startServices(contract, executionPolicy, resources, labels, securityOptions, sink, signal) {
+        const started = [];
+        for (const service of contract.contract.services) {
+            const image = serviceImage(service.type);
+            if (!image)
+                throw new Error(`service_unavailable: no digest-pinned catalogue image configured for ${service.type}.`);
+            await this.verifyCatalogImage(image, executionPolicy, sink, signal);
+            const name = `${resources.prefix}-${service.type}`;
+            const args = serviceContainerArgs(service, image, resources, labels, securityOptions);
+            const containerId = dockerObjectId((await this.docker(args, 60_000, signal)).stdout, "container");
+            await this.waitForServiceHealthy(name, signal);
+            started.push({ id: containerId, name, role: `service:${service.type}` });
+        }
+        return started;
+    }
+    async verifyCatalogImage(image, executionPolicy, sink, signal) {
+        if (this.verifiedCatalogImages.has(image))
+            return;
+        const status = await verifySandboxImageSignature({ image, executionPolicy, signal });
+        if (status === "passed") {
+            this.verifiedCatalogImages.add(image);
+            return;
+        }
+        await sink.emit(event("sandbox_image_signature_warning", `Image signature enforcement is not configured for adoption-mode image ${image}.`));
+    }
+    async waitForServiceHealthy(name, signal) {
+        const deadline = Date.now() + 60_000;
+        while (Date.now() < deadline) {
+            if (signal?.aborted)
+                throw new Error(String(signal.reason ?? "sandbox service startup cancelled"));
+            const status = (await this.docker(["container", "inspect", name, "--format", "{{.State.Health.Status}}"], 10_000, signal)).stdout.trim();
+            if (status === "healthy")
+                return;
+            if (status === "unhealthy")
+                throw new Error(`sandbox_service_health_timeout: ${name} reported unhealthy.`);
+            await new Promise(resolve => setTimeout(resolve, 500));
+        }
+        throw new Error(`sandbox_service_health_timeout: ${name} did not become healthy before the startup deadline.`);
+    }
+    async teardown(resources, expectedLabels, source, includeCredentials = true) {
+        const attemptId = expectedLabels["dev.forge.dispatch-attempt-id"];
+        const reportId = randomUUID();
+        const actions = [];
+        const record = async (kind, id) => {
+            try {
+                await this.removeResource(kind, id);
+                actions.push(cleanupAction(expectedLabels, kind, id, "removed"));
+            }
+            catch (error) {
+                actions.push(cleanupAction(expectedLabels, kind, id, "failed", cleanupErrorMessage(error)));
+            }
+        };
+        for (const id of await this.listResources("container", `dev.forge.dispatch-attempt-id=${attemptId}`, false)) {
+            try {
+                const labels = await this.inspectResourceLabels("container", id);
+                if (!labelsMatch(labels, expectedLabels))
+                    continue;
+                await record("container", id);
+            }
+            catch (error) {
+                actions.push(cleanupAction(expectedLabels, "container", id, "failed", cleanupErrorMessage(error)));
+            }
+        }
+        for (const [kind, names] of [["network", [resources.network, resources.egressNetwork]], ["volume", sandboxRuntimeCleanupVolumeNames(resources, includeCredentials)]]) {
+            for (const name of names) {
+                if (!name)
+                    continue;
+                const labels = await this.inspectResourceLabels(kind, name).catch(() => null);
+                if (labels && labelsMatch(labels, expectedLabels))
+                    await record(kind, name);
+            }
+        }
+        const remaining = (await Promise.all(["container", "network", "volume"].map(async (kind) => ({
+            kind,
+            ids: await this.listResources(kind, `dev.forge.dispatch-attempt-id=${attemptId}`, false)
+        })))).flatMap(entry => entry.ids.map(id => ({ kind: entry.kind, id })));
+        const reportedFailures = new Set(actions.filter(action => action.outcome === "failed").map(action => `${action.resourceType}\0${action.resourceId}`));
+        for (const resource of remaining) {
+            if (!reportedFailures.has(`${resource.kind}\0${resource.id}`)) {
+                actions.push(cleanupAction(expectedLabels, resource.kind, resource.id, "failed", "Exact-labeled resource remained after teardown."));
+            }
+        }
+        const report = { reportId, source, actions };
+        if (remaining.length > 0 || actions.some(action => action.outcome === "failed")) {
+            throw new SandboxTeardownError(report, `teardown_failed: ${remaining.length} exact-labeled Docker resources remain for attempt ${attemptId}.`);
+        }
+        return report;
+    }
+    async listResources(kind, label, suppressErrors = true) {
+        const args = kind === "container"
+            ? ["ps", "-aq", "--filter", `label=${label}`]
+            : [kind, "ls", "-q", "--filter", `label=${label}`];
+        const result = suppressErrors ? await this.docker(args, 30_000).catch(() => null) : await this.docker(args, 30_000);
+        return result?.stdout.split(/\s+/).filter(Boolean) ?? [];
+    }
+    async inspectResourceLabels(kind, id) {
+        const args = kind === "container" ? ["container", "inspect", id] : [kind, "inspect", id];
+        const result = await this.docker(args, 15_000, undefined, 256 * 1024);
+        const document = JSON.parse(result.stdout);
+        return document[0]?.Config?.Labels ?? document[0]?.Labels ?? {};
+    }
+    async removeResource(kind, id) {
+        if (kind === "container") {
+            await this.docker(["container", "stop", "--time", "10", id], 20_000).catch(() => undefined);
+        }
+        const args = kind === "container" ? ["container", "rm", "--force", id] : kind === "volume" ? ["volume", "rm", "--force", id] : ["network", "rm", id];
+        await this.docker(args, 30_000);
+    }
+    async writeImageCacheRecord(record) {
+        const root = path.join(this.config.sandboxStateRoot, "image-cache");
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const target = path.join(root, `${record.key}.json`);
+        const previous = await this.readImageCacheRecord(target);
+        const value = previous ? { ...record, createdAt: previous.createdAt } : record;
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        await fs.writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: "wx" });
+        await fs.rename(temporary, target);
+    }
+    async readImageCacheRecords() {
+        const root = path.join(this.config.sandboxStateRoot, "image-cache");
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const records = [];
+        for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+            if (!entry.isFile() || !/^[0-9a-f]{64}\.json$/i.test(entry.name))
+                continue;
+            const record = await this.readImageCacheRecord(path.join(root, entry.name));
+            if (record)
+                records.push(record);
+        }
+        return records;
+    }
+    async readImageCacheRecord(target) {
+        const stat = await fs.lstat(target).catch(() => null);
+        if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024)
+            return null;
+        const value = await fs.readFile(target, "utf8").then(text => JSON.parse(text)).catch(() => null);
+        return value && validImageCacheRecord(value) ? value : null;
+    }
+    async collectExpiredImages() {
+        const records = await this.readImageCacheRecords();
+        const candidates = selectImageGcCandidates(records, Math.max(1, Math.floor(this.config.imageRetentionCount)), Math.max(60_000, this.config.imageRetentionTtlMs), Date.now());
+        const protectedDigests = new Set([...this.active.values()]
+            .map(value => value.ledger?.labels["dev.forge.image-digest"])
+            .filter((value) => Boolean(value)));
+        for (const record of candidates) {
+            if (protectedDigests.has(record.imageDigest) || protectedDigests.has(record.helperImageDigest))
+                continue;
+            for (const tag of [record.overlayTag, record.helperTag, record.projectTag]) {
+                await this.docker(["image", "rm", tag], 60_000).catch(() => undefined);
+            }
+            const remains = await Promise.all([record.overlayTag, record.helperTag, record.projectTag]
+                .map(tag => this.docker(["image", "inspect", tag, "--format", "{{.Id}}"], 15_000).then(() => true).catch(() => false)));
+            if (!remains.some(Boolean)) {
+                await fs.rm(path.join(this.config.sandboxStateRoot, "image-cache", `${record.key}.json`), { force: true });
+            }
+        }
+        const builder = dedicatedBuildxBuilderName(this.config.runnerId, this.config.dockerContext);
+        const builderExists = await this.docker(["buildx", "inspect", builder], 30_000).then(() => true).catch(() => false);
+        if (builderExists) {
+            await this.docker([
+                "buildx", "prune", "--builder", builder, "--force",
+                "--max-used-space", boundedBuildCacheSize(process.env.FORGE_SANDBOX_BUILDKIT_CACHE_MAX, "20gb"),
+                "--min-free-space", String(Math.max(1, Math.floor(this.config.minimumWorkspaceBytes))),
+                "--reserved-space", boundedBuildCacheSize(process.env.FORGE_SANDBOX_BUILDKIT_CACHE_RESERVED, "2gb")
+            ], 5 * 60_000, undefined, 4 * 1024 * 1024).catch(() => undefined);
+        }
+    }
+    async purgeRestrictedAuditArtifacts() {
+        const activeDigests = new Set([...this.active.values()]
+            .map(value => value.ledger?.labels["dev.forge.image-digest"])
+            .filter((value) => Boolean(value)));
+        const protectedKeys = new Set((await this.readImageCacheRecords())
+            .filter(record => activeDigests.has(record.imageDigest) || activeDigests.has(record.helperImageDigest))
+            .map(record => record.key));
+        for (const name of ["build-logs", "attestations"]) {
+            const root = path.join(this.config.sandboxStateRoot, name);
+            const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+            const records = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory() || !/^[0-9a-f]{64}$/iu.test(entry.name))
+                    continue;
+                const target = path.join(root, entry.name);
+                const stat = await fs.lstat(target).catch(() => null);
+                if (!stat?.isDirectory() || stat.isSymbolicLink())
+                    continue;
+                records.push({ key: entry.name.toLowerCase(), lastModifiedMs: stat.mtimeMs });
+            }
+            const candidates = selectAuditArtifactGcCandidates(records, Math.max(1, Math.floor(this.config.auditRetentionCount)), Math.max(60 * 60_000, this.config.auditRetentionTtlMs), protectedKeys);
+            for (const key of candidates) {
+                await fs.rm(path.join(root, key), { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+    }
+    docker(args, timeoutMs, signal, maxOutputBytes = 1024 * 1024) {
+        return requireSandboxProcess({ command: this.config.dockerExecutable, args: this.dockerArgs(args), timeoutMs, maxOutputBytes, signal });
+    }
+    dockerArgs(args) { return this.config.dockerContext ? ["--context", this.config.dockerContext, ...args] : [...args]; }
+}
+class HostGit {
+    config;
+    repoPath;
+    coordinator;
+    constructor(config, repoPath) {
+        this.config = config;
+        this.repoPath = repoPath;
+        this.coordinator = new RepositoryCoordinatorLock(config.sandboxStateRoot);
+    }
+    async prepare(dispatch, attemptRoot, signal) {
+        return await this.coordinator.withLock(this.repoPath, () => this.prepareLocked(dispatch, attemptRoot), signal);
+    }
+    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 configSelection = selectSandboxConfigRefs(dispatch.sandbox.executionPolicy, dispatch.sandbox.sandboxConfigCommitSha, dispatch.repo.defaultBranch);
+        const configCommitSha = await this.resolveFirst([...configSelection.refs]);
+        const approvedConfigSha = configSelection.approvedSha;
+        if (approvedConfigSha && configCommitSha !== approvedConfigSha) {
+            throw new Error("sandbox_config_commit_mismatch: approved sandbox config commit resolved to a different object.");
+        }
+        const contractSource = (await this.git(["show", `${configCommitSha}:.forge/forge.sandbox.yml`], 30_000)).stdout;
+        const dockerfile = (await this.git(["show", `${configCommitSha}:.forge/Dockerfile`], 30_000)).stdout;
+        const inputRef = `refs/forge/inputs/${dispatch.sandbox.dispatchAttemptId.replace(/-/g, "")}`;
+        const bundlePath = path.join(attemptRoot, "input", "repo.bundle");
+        await this.git(["update-ref", inputRef, inputCommitSha], 30_000);
+        try {
+            await this.git(["bundle", "create", bundlePath, inputRef], 5 * 60_000);
+        }
+        finally {
+            await this.git(["update-ref", "-d", inputRef], 30_000).catch(() => null);
+        }
+        const contextArchive = path.join(attemptRoot, "input", "context.tar");
+        await this.git(["archive", "--format=tar", "--output", contextArchive, configCommitSha], 5 * 60_000);
+        const contextRoot = path.join(attemptRoot, "context");
+        await fs.mkdir(contextRoot, { recursive: true });
+        await requireSandboxProcess({ command: "tar", args: ["-xf", contextArchive, "-C", contextRoot], timeoutMs: 5 * 60_000, maxOutputBytes: 1024 * 1024 });
+        const contextDigest = createHash("sha256").update(await fs.readFile(contextArchive)).digest("hex");
+        return { inputCommitSha, configCommitSha, contractSource, dockerfile, bundlePath, contextRoot, contextDigest };
+    }
+    async importResult(dispatch, output, assertCurrent) {
+        await this.coordinator.withLock(this.repoPath, () => this.importResultLocked(dispatch, output, assertCurrent));
+    }
+    async publishResult(dispatch, output, assertCurrent, credential, signal) {
+        await this.coordinator.withLock(this.repoPath, async () => {
+            const handle = dispatch.sandbox?.publishGrantHandle;
+            const resultCommitSha = output.manifest.resultCommitSha;
+            if (dispatch.sandbox?.publicationMode !== "bridge_push"
+                || !handle
+                || !resultCommitSha
+                || handle.branch !== dispatch.lease.worktreeKey
+                || !/^[0-9a-f-]{32,36}$/iu.test(handle.grantId)) {
+                throw new Error("sandbox_output_publish_forbidden: remote publication grant is missing or outside its attempt scope.");
+            }
+            assertCurrent();
+            const credentialEnvironment = publicationCredentialEnvironment(credential);
+            await this.git(["check-ref-format", "--branch", handle.branch], 30_000, signal);
+            const remoteRef = `refs/heads/${handle.branch}`;
+            const remote = await this.git(["ls-remote", "--heads", credential.remoteUrl, remoteRef], 60_000, signal, credentialEnvironment);
+            const remoteSha = remote.stdout.trim().split(/\s+/u)[0] ?? "";
+            const pushArgs = publicationPushArgs(handle.branch, resultCommitSha, output.manifest.inputCommitSha, remoteSha, credential.remoteUrl);
+            if (!pushArgs) {
+                assertCurrent();
+                return;
+            }
+            assertCurrent();
+            await this.git(pushArgs, 5 * 60_000, signal, credentialEnvironment);
+            assertCurrent();
+        });
+    }
+    async importResultLocked(dispatch, output, assertCurrent) {
+        if (!output.bundlePath || !output.manifest.resultCommitSha)
+            return;
+        await this.git(["bundle", "verify", output.bundlePath], 2 * 60_000);
+        const attemptHex = dispatch.sandbox.dispatchAttemptId.replace(/-/g, "");
+        const sourceRef = `refs/forge/results/${attemptHex}`;
+        const importRef = `refs/forge/imports/${attemptHex}`;
+        const quarantine = path.join(this.config.sandboxStateRoot, "quarantine", attemptHex);
+        await fs.rm(quarantine, { recursive: true, force: true });
+        await fs.mkdir(path.dirname(quarantine), { recursive: true, mode: 0o700 });
+        await requireSandboxProcess({ command: "git", args: ["init", "--bare", quarantine], timeoutMs: 30_000, maxOutputBytes: 1024 * 1024 });
+        try {
+            await quarantineGit(quarantine, ["fetch", "--no-write-fetch-head", output.bundlePath, `${sourceRef}:${importRef}`], 5 * 60_000);
+            await quarantineGit(quarantine, ["fsck", "--strict", "--full", "--no-reflogs"], 5 * 60_000);
+            const objectInventory = await runSandboxProcess({
+                command: "git",
+                args: ["-C", quarantine, "cat-file", "--batch-all-objects", "--batch-check=%(objectname) %(objecttype) %(objectsize)"],
+                timeoutMs: 2 * 60_000,
+                maxOutputBytes: 64 * 1024 * 1024,
+                terminateOnOutputLimit: true
+            });
+            if (objectInventory.exitCode !== 0 || objectInventory.truncated) {
+                throw new Error("sandbox_output_invalid: Git bundle exceeds object validation limits.");
+            }
+            validateGitObjectBudget(objectInventory.stdout);
+            const imported = (await quarantineGit(quarantine, ["rev-parse", `${importRef}^{commit}`], 30_000)).stdout.trim();
+            if (imported !== output.manifest.resultCommitSha)
+                throw new Error("sandbox_output_invalid: imported result SHA differs from manifest.");
+            const ancestry = await runSandboxProcess({ command: "git", args: ["-C", quarantine, "merge-base", "--is-ancestor", output.manifest.inputCommitSha, imported], timeoutMs: 30_000 });
+            if (ancestry.exitCode !== 0)
+                throw new Error("sandbox_output_invalid: result commit is not descended from input commit.");
+            const commitDepth = await quarantineGit(quarantine, ["rev-list", "--count", `${output.manifest.inputCommitSha}..${imported}`], 2 * 60_000);
+            validateGitCommitDepth(commitDepth.stdout);
+            await this.git(["fetch", "--no-write-fetch-head", quarantine, `${importRef}:${importRef}`], 5 * 60_000);
+            try {
+                assertCurrent();
+                await this.updateManagedBranch(dispatch.lease.worktreeKey, imported, output.manifest.inputCommitSha);
+            }
+            finally {
+                await this.git(["update-ref", "-d", importRef], 30_000).catch(() => null);
+            }
+        }
+        finally {
+            await fs.rm(quarantine, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    async updateManagedBranch(worktreeKey, imported, expected) {
+        const branchRef = `refs/heads/${worktreeKey}`;
+        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);
+            return;
+        }
+        const head = (await requireSandboxProcess({ command: "git", args: ["-C", checkedOut.path, "rev-parse", "HEAD"], timeoutMs: 30_000 })).stdout.trim();
+        const status = (await requireSandboxProcess({ command: "git", args: ["-C", checkedOut.path, "status", "--porcelain=v1", "--untracked-files=no"], timeoutMs: 30_000, maxOutputBytes: 4 * 1024 * 1024 })).stdout;
+        if (head !== expected || status.trim())
+            throw new Error("sandbox_output_conflict: managed worktree changed after sandbox input was captured.");
+        await this.git(["update-ref", branchRef, imported, expected], 30_000);
+        await requireSandboxProcess({ command: "git", args: ["-C", checkedOut.path, "reset", "--hard"], timeoutMs: 2 * 60_000, maxOutputBytes: 4 * 1024 * 1024 });
+    }
+    async resolveFirst(refs) {
+        for (const ref of refs) {
+            const result = await runSandboxProcess({ command: "git", args: ["-C", this.repoPath, "rev-parse", "--verify", `${ref}^{commit}`], timeoutMs: 30_000 });
+            const sha = result.stdout.trim();
+            if (result.exitCode === 0 && /^[0-9a-f]{40,64}$/i.test(sha))
+                return sha;
+        }
+        throw new Error("sandbox_input_failed: no approved input Git ref could be resolved.");
+    }
+    git(args, timeoutMs, signal, env) { return requireSandboxProcess({ command: "git", args: ["-C", this.repoPath, ...args], timeoutMs, maxOutputBytes: 4 * 1024 * 1024, signal, env }); }
+}
+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))) {
+        throw new Error("sandbox_output_publish_rejected: publication inputs contain an invalid branch or object id.");
+    }
+    if (remoteCommitSha === resultCommitSha)
+        return null;
+    if (remoteCommitSha && remoteCommitSha !== inputCommitSha) {
+        throw new Error("sandbox_output_publish_stale: remote branch changed after the sandbox input was captured.");
+    }
+    const remoteRef = `refs/heads/${branch}`;
+    return [
+        "push",
+        "--porcelain",
+        remote,
+        `${resultCommitSha}:${remoteRef}`,
+        `--force-with-lease=${remoteRef}:${remoteCommitSha}`
+    ];
+}
+export function validatePublicationCredential(credential, nowMs = Date.now()) {
+    const remote = (() => { try {
+        return new URL(credential.remoteUrl);
+    }
+    catch {
+        return null;
+    } })();
+    if (!remote
+        || remote.protocol !== "https:"
+        || remote.hostname.toLowerCase() !== "github.com"
+        || remote.port
+        || remote.username
+        || remote.password
+        || remote.search
+        || remote.hash
+        || !/^\/[a-z0-9_.-]+\/[a-z0-9_.-]+\.git$/iu.test(remote.pathname)
+        || !/^[a-z0-9_-]{1,64}$/iu.test(credential.username)
+        || !credential.secret
+        || credential.secret.length > 16 * 1024
+        || /[\r\n\0]/u.test(credential.secret)
+        || Date.parse(credential.expiresAt) <= nowMs) {
+        throw new Error("sandbox_output_publish_forbidden: redeemed publication credential is invalid or expired.");
+    }
+}
+export function publicationCredentialEnvironment(credential, environment = process.env) {
+    validatePublicationCredential(credential);
+    const authorization = Buffer.from(`${credential.username}:${credential.secret}`, "utf8").toString("base64");
+    return {
+        ...environment,
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: "http.https://github.com/.extraHeader",
+        GIT_CONFIG_VALUE_0: `Authorization: Basic ${authorization}`,
+        GIT_TERMINAL_PROMPT: "0",
+        GCM_INTERACTIVE: "Never"
+    };
+}
+export function restrictedBuildLog(source, exactSecrets = [], maximumBytes = 4 * 1024 * 1024) {
+    const limit = Math.max(1024, Math.min(maximumBytes, 4 * 1024 * 1024));
+    const redacted = Buffer.from(redactText(source, exactSecrets), "utf8");
+    const truncated = redacted.length > limit;
+    const retained = truncated ? redacted.subarray(0, limit) : redacted;
+    return {
+        content: retained.toString("utf8"),
+        digest: `sha256:${createHash("sha256").update(retained).digest("hex")}`,
+        byteCount: retained.length,
+        truncated
+    };
+}
+export function validateGitObjectBudget(inventory, maximumObjectCount = 500_000, maximumExpandedBytes = 2 * 1024 * 1024 * 1024) {
+    const lines = inventory.split(/\r?\n/u).filter(Boolean);
+    if (lines.length === 0 || lines.length > maximumObjectCount) {
+        throw new Error("sandbox_output_invalid: Git bundle exceeds the object-count budget.");
+    }
+    const maximum = BigInt(maximumExpandedBytes);
+    let expanded = 0n;
+    const objects = new Set();
+    for (const line of lines) {
+        const match = /^([0-9a-f]{40}|[0-9a-f]{64}) (blob|tree|commit|tag) ([0-9]+)$/iu.exec(line);
+        if (!match || objects.has(match[1].toLowerCase())) {
+            throw new Error("sandbox_output_invalid: Git object inventory is malformed or duplicated.");
+        }
+        objects.add(match[1].toLowerCase());
+        const size = BigInt(match[3]);
+        expanded += size;
+        if (size > maximum || expanded > maximum) {
+            throw new Error("sandbox_output_invalid: Git bundle exceeds the expanded-object byte budget.");
+        }
+    }
+    return { objectCount: lines.length, expandedBytes: Number(expanded) };
+}
+export function validateGitCommitDepth(value, maximumCommitDepth = 50_000) {
+    const normalized = value.trim();
+    if (!/^[0-9]+$/u.test(normalized)) {
+        throw new Error("sandbox_output_invalid: Git commit-depth result is malformed.");
+    }
+    const depth = BigInt(normalized);
+    if (depth > BigInt(maximumCommitDepth)) {
+        throw new Error("sandbox_output_invalid: Git result exceeds the commit-depth budget.");
+    }
+    return Number(depth);
+}
+export function selectAuditArtifactGcCandidates(records, retentionCount, retentionTtlMs, protectedKeys = new Set(), nowMs = Date.now()) {
+    const count = Math.max(1, Math.floor(retentionCount));
+    const ttl = Math.max(60 * 60_000, retentionTtlMs);
+    return records
+        .filter(record => !protectedKeys.has(record.key))
+        .sort((left, right) => right.lastModifiedMs - left.lastModifiedMs)
+        .filter((record, index) => index >= count || nowMs - record.lastModifiedMs > ttl)
+        .map(record => record.key);
+}
+export function selectSandboxConfigRefs(executionPolicy, configuredSha, defaultBranch) {
+    const approvedSha = configuredSha?.trim().toLowerCase() || null;
+    if (executionPolicy === "sandbox_required" && !approvedSha) {
+        throw new Error("sandbox_config_commit_unapproved: sandbox_required dispatches need a server-approved config commit SHA.");
+    }
+    if (approvedSha && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(approvedSha)) {
+        throw new Error("sandbox_config_commit_invalid: approved sandbox config commit is not a full Git object id.");
+    }
+    return approvedSha
+        ? { refs: [approvedSha], approvedSha }
+        : { refs: [`refs/remotes/origin/${defaultBranch}`, `refs/heads/${defaultBranch}`], approvedSha: null };
+}
+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);
+    return { hardWallMs: hardWallSeconds * 1000, idleMs: idleSeconds * 1000 };
+}
+function boundedInteger(value, fallback, minimum, maximum) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+}
+function quarantineGit(repoPath, args, timeoutMs) {
+    return requireSandboxProcess({
+        command: "git",
+        args: ["-C", repoPath, "-c", "transfer.fsckObjects=true", "-c", "fetch.fsckObjects=true", ...args],
+        timeoutMs,
+        maxOutputBytes: 16 * 1024 * 1024,
+        env: { ...process.env, GIT_NO_REPLACE_OBJECTS: "1" }
+    });
+}
+function parseWorktreeListing(value) {
+    return value.trim().split(/\r?\n\r?\n/u).map(block => {
+        const lines = block.split(/\r?\n/u);
+        return {
+            path: lines.find(line => line.startsWith("worktree "))?.slice(9) ?? "",
+            branch: lines.find(line => line.startsWith("branch "))?.slice(7) ?? null
+        };
+    }).filter(entry => path.isAbsolute(entry.path));
+}
+async function validateOutput(attemptRoot, dispatch) {
+    const outputRoot = path.join(attemptRoot, "output");
+    const manifestPath = path.join(outputRoot, "manifest.json");
+    const stat = await fs.lstat(manifestPath);
+    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"));
+    if (!dispatch.sandbox
+        || manifest.dispatchAttemptId !== dispatch.sandbox.dispatchAttemptId
+        || manifest.executionLeaseId !== dispatch.sandbox.executionLeaseId
+        || manifest.fencingToken !== dispatch.lease.fencingToken
+        || manifest.runnerInstanceId !== dispatch.sandbox.runnerInstanceId
+        || manifest.inputCommitSha !== dispatch.sandbox.inputCommitSha
+        || manifest.branch !== dispatch.lease.worktreeKey
+        || manifest.contractDigest !== dispatch.sandbox.contractDigest
+        || manifest.imageDigest !== dispatch.sandbox.imageDigest)
+        throw new Error("sandbox_output_invalid: manifest identity or fence mismatch.");
+    if ((manifest.resultCommitSha === null) !== (manifest.bundle === null)
+        || (manifest.resultCommitSha !== null && !/^[0-9a-f]{40,64}$/i.test(manifest.resultCommitSha))) {
+        throw new Error("sandbox_output_invalid: result commit and bundle must be present together.");
+    }
+    const resultPath = await validateManifestFile(outputRoot, manifest.result, 16 * 1024 * 1024);
+    const bundlePath = manifest.bundle ? await validateManifestFile(outputRoot, manifest.bundle, 512 * 1024 * 1024) : null;
+    return { manifest, resultPath, bundlePath };
+}
+async function validateManifestFile(root, file, max) {
+    if (!/^[a-z0-9_.-]+$/i.test(file.path))
+        throw new Error("sandbox_output_invalid: output path is invalid.");
+    const target = path.join(root, file.path);
+    const stat = await fs.lstat(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== file.bytes || stat.size > max)
+        throw new Error("sandbox_output_invalid: output file bounds mismatch.");
+    const digest = createHash("sha256").update(await fs.readFile(target)).digest("hex");
+    if (digest !== file.sha256)
+        throw new Error("sandbox_output_invalid: output hash mismatch.");
+    return target;
+}
+function identityFor(dispatch) {
+    const value = dispatch.sandbox?.dispatchAttemptId.replace(/-/g, "").toLowerCase() ?? "";
+    if (!/^[0-9a-f]{32}$/.test(value))
+        throw new Error("sandbox_identity_invalid: dispatch attempt id must be a full UUID.");
+    return { attemptHex: value };
+}
+class SandboxTeardownError extends Error {
+    report;
+    constructor(report, message) {
+        super(message);
+        this.report = report;
+        this.name = "SandboxTeardownError";
+    }
+}
+function emptyCleanupReport(source) {
+    return { reportId: randomUUID(), source, actions: [] };
+}
+function cleanupAction(labels, resourceType, resourceId, outcome, message = null) {
+    return {
+        dispatchAttemptId: labels["dev.forge.dispatch-attempt-id"] ?? "",
+        fencingToken: labels["dev.forge.fencing-token"] ?? "",
+        runnerInstanceId: labels["dev.forge.runner-instance-id"] ?? "",
+        resourceType,
+        resourceId: resourceId.slice(0, 255),
+        outcome,
+        message,
+        occurredAt: new Date().toISOString()
+    };
+}
+function cleanupErrorMessage(error) {
+    return redactText(error instanceof Error ? error.message : String(error)).replace(/[\r\n\t]+/gu, " ").trim().slice(0, 1000)
+        || "Docker resource removal failed.";
+}
+function parseCleanupReport(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const report = value;
+    if (typeof report.reportId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(report.reportId))
+        return null;
+    if (report.source !== "teardown" && report.source !== "reaper")
+        return null;
+    if (!Array.isArray(report.actions) || report.actions.length > 128)
+        return null;
+    const actions = [];
+    for (const candidate of report.actions) {
+        if (!candidate || typeof candidate !== "object")
+            return null;
+        const action = candidate;
+        if (typeof action.dispatchAttemptId !== "string" || !/^[0-9a-f-]{32,36}$/iu.test(action.dispatchAttemptId)
+            || typeof action.fencingToken !== "string" || !/^[0-9a-f-]{32,36}$/iu.test(action.fencingToken)
+            || typeof action.runnerInstanceId !== "string" || !/^[0-9a-f-]{32,36}$/iu.test(action.runnerInstanceId)
+            || (action.resourceType !== "container" && action.resourceType !== "network" && action.resourceType !== "volume")
+            || typeof action.resourceId !== "string" || action.resourceId.length === 0 || action.resourceId.length > 255 || hasControlCharacters(action.resourceId)
+            || (action.outcome !== "removed" && action.outcome !== "failed")
+            || (action.message != null && (typeof action.message !== "string" || action.message.length > 1000))
+            || typeof action.occurredAt !== "string" || !Number.isFinite(Date.parse(action.occurredAt)))
+            return null;
+        actions.push(action);
+    }
+    return { reportId: report.reportId, source: report.source, actions };
+}
+function hasControlCharacters(value) {
+    return [...value].some(character => {
+        const code = character.codePointAt(0) ?? 0;
+        return code < 32 || code === 127;
+    });
+}
+export function assertSandboxImportCurrent(expected, current, signal, nowMs = Date.now()) {
+    if (signal.aborted
+        || !current
+        || current.dispatchAttemptId !== expected.dispatchAttemptId
+        || current.fencingToken !== expected.fencingToken
+        || Date.parse(expected.expiresAt) <= nowMs) {
+        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 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) {
+    const id = output.trim();
+    if (!/^[0-9a-f]{12,64}$/iu.test(id)) {
+        throw new Error(`sandbox_create_failed: Docker returned an invalid ${kind} id.`);
+    }
+    return id.toLowerCase();
+}
+export function sandboxRuntimeVolumes(resources, includeEgressPolicy = true, includeCredentials = true) {
+    return [
+        { name: resources.workspaceVolume, role: "workspace" },
+        { name: resources.controlVolume, role: "control" },
+        { name: resources.secretsVolume, role: "secrets" },
+        ...(includeCredentials ? [{ name: resources.credentialsVolume, role: "credentials" }] : []),
+        ...(includeEgressPolicy ? [{ name: resources.egressConfigVolume, role: "egress_policy" }] : []),
+        ...Object.entries(resources.cacheVolumes).map(([cache, name]) => ({ name, role: `cache:${cache}` }))
+    ];
+}
+export function sandboxRuntimeCleanupVolumeNames(resources, includeCredentials = true) {
+    return sandboxRuntimeVolumes(resources, true, includeCredentials)
+        .map(volume => volume.name)
+        .filter((name) => typeof name === "string" && name.length > 0);
+}
+function labelsFor(dispatch, image, contract) {
+    return {
+        "dev.forge.managed": "true", "dev.forge.session-id": dispatch.session.id, "dev.forge.execution-lease-id": dispatch.sandbox.executionLeaseId,
+        "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,
+        "dev.forge.initial-expires-at": dispatch.lease.expiresAt
+    };
+}
+function labelArgs(labels) { return Object.entries(labels).flatMap(([key, value]) => ["--label", `${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"];
+    return labels["dev.forge.managed"] === "true"
+        && labels["dev.forge.runner-id"] === runnerId
+        && Boolean(attemptId)
+        && !liveAttempts.has(attemptId);
+}
+export function shouldReapSandboxLedger(ledger, currentRunnerInstanceId, serverAttempt, snapshotAvailable, nowMs = Date.now()) {
+    if (ledger.runnerInstanceId !== currentRunnerInstanceId)
+        return true;
+    if (!snapshotAvailable)
+        return Date.parse(ledger.expiresAt) <= nowMs;
+    return !serverAttempt
+        || serverAttempt.dispatchAttemptId !== ledger.dispatchAttemptId
+        || serverAttempt.fencingToken !== ledger.fencingToken
+        || serverAttempt.runnerInstanceId !== ledger.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) {
+    return [
+        "--label", managedLabel,
+        "--label", `dev.forge.project=${dockerLabelValue(project)}`,
+        "--label", `dev.forge.image-key=${key}`,
+        "--label", `dev.forge.image-kind=${kind}`
+    ];
+}
+function validImageCacheRecord(value) {
+    return value?.schemaVersion === 1
+        && /^[0-9a-f]{64}$/i.test(value.key)
+        && typeof value.project === "string"
+        && Number.isFinite(Date.parse(value.createdAt))
+        && Number.isFinite(Date.parse(value.lastUsedAt))
+        && [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)
+        && /^[0-9a-f]{64}$/i.test(value.policyDigest);
+}
+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) {
+    const absolute = /^[A-Za-z]:[\\/]/u.test(layoutPath) ? layoutPath : path.resolve(layoutPath);
+    const normalized = absolute.replace(/\\/gu, "/");
+    // 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.
+    return normalized.startsWith("/") ? `oci-layout://${normalized}` : `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 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/bin/codex /usr/local/bin/codex
+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 (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);
+    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)
+    };
+}
+export function dedicatedBuildxBuilderName(runnerId, dockerContext) {
+    const identity = `${runnerId}\0${dockerContext || "default"}`;
+    return `forge-${createHash("sha256").update(identity).digest("hex").slice(0, 20)}`;
+}
+export function dedicatedBuildxBuilderContainerName(builder) {
+    if (!/^forge-[0-9a-f]{20}$/u.test(builder))
+        throw new Error("sandbox_build_failed: invalid dedicated builder name.");
+    return `buildx_buildkit_${builder}0`;
+}
+function boundedBuildCacheSize(value, fallback) {
+    const normalized = value?.trim().toLowerCase();
+    const match = /^(\d+)(gb|mb)$/u.exec(normalized ?? "");
+    if (!match)
+        return fallback;
+    const bytes = Number(match[1]) * (match[2] === "gb" ? 1024 ** 3 : 1024 ** 2);
+    return bytes >= 512 * 1024 ** 2 && bytes <= 200 * 1024 ** 3 ? normalized : fallback;
+}
+export function selectImageGcCandidates(records, keepPerProject, ttlMs, nowMs) {
+    const groups = new Map();
+    for (const record of records)
+        groups.set(record.project, [...(groups.get(record.project) ?? []), record]);
+    const cutoff = nowMs - ttlMs;
+    return [...groups.values()].flatMap(group => group
+        .sort((left, right) => Date.parse(right.lastUsedAt) - Date.parse(left.lastUsedAt))
+        .slice(Math.max(1, keepPerProject))
+        .filter(record => Date.parse(record.lastUsedAt) <= cutoff));
+}
+async function sandboxProviderAuthForDispatch(dispatch) {
+    const unavailable = sandboxProviderAuthUnavailableMessage(dispatch.execution.provider, dispatch.execution.authKind);
+    if (unavailable) {
+        throw new Error(`sandbox_auth_unavailable: ${unavailable}`);
+    }
+    const adapter = sandboxProviderAuthAdapterFor(dispatch.execution.provider, dispatch.execution.authKind);
+    return adapter ? adapter.prepareAttemptAuth() : null;
+}
+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"];
+}
+function providerAuthVolumeArgs(dispatch, resources) {
+    const adapter = sandboxProviderAuthAdapterFor(dispatch.execution.provider, dispatch.execution.authKind);
+    if (!adapter) {
+        return [];
+    }
+    return ["--volume", `${resources.credentialsVolume}:${adapter.containerMountPath}:${adapter.writable ? "rw" : "ro"}`];
+}
+export function cacheVolumeArgs(contract, resources) {
+    const targets = {
+        npm: "/home/forge/.npm", pnpm: "/home/forge/.local/share/pnpm/store", yarn: "/home/forge/.cache/yarn",
+        nuget: "/home/forge/.nuget/packages", cargo: "/home/forge/.cargo/registry", pip: "/home/forge/.cache/pip"
+    };
+    return contract.contract.caches
+        .filter(cache => cache.mode === "per_attempt")
+        .flatMap(cache => ["--volume", `${resources.cacheVolumes[cache.name]}:${targets[cache.name]}`]);
+}
+export function proxyEnvironmentArgs(dispatch, contract, resources) {
+    if (dispatch.sandbox.networkPolicy.mode !== "public_allowlist")
+        return [];
+    const bypass = ["localhost", "127.0.0.1", "::1", ...contract.contract.services.map(service => `${resources.prefix}-${service.type}`)].join(",");
+    return ["--env", "HTTP_PROXY=http://forge-egress:3128", "--env", "HTTPS_PROXY=http://forge-egress:3128", "--env", "ALL_PROXY=http://forge-egress:3128", "--env", `NO_PROXY=${bypass}`];
+}
+export function egressProxyConfig(allowedHosts) {
+    const domains = allowedHosts.map(host => host.startsWith("*.") ? `.${host.slice(2)}` : host).join(" ");
+    if (!domains)
+        throw new Error("sandbox_egress_policy_invalid: public_allowlist requires at least one approved host.");
+    return [
+        "http_port 3128",
+        "access_log none",
+        "cache deny all",
+        "acl SSL_ports port 443",
+        "acl Safe_ports port 80 443",
+        "acl CONNECT method CONNECT",
+        "acl private_dst dst 0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16 172.16.0.0/12 192.0.0.0/24 192.168.0.0/16 198.18.0.0/15 224.0.0.0/4 240.0.0.0/4 ::1/128 fc00::/7 fe80::/10",
+        `acl forge_allowed dstdomain ${domains}`,
+        "http_access deny private_dst",
+        "http_access deny !Safe_ports",
+        "http_access deny CONNECT !SSL_ports",
+        "http_access allow forge_allowed",
+        "http_access deny all",
+        "shutdown_lifetime 1 seconds",
+        "visible_hostname forge-egress"
+    ].join("\n") + "\n";
+}
+export function serviceContainerArgs(service, image, resources, labels, securityOptions, environment = process.env) {
+    const name = `${resources.prefix}-${service.type}`;
+    const serviceUser = service.type === "browser" ? "10001:10001" : "999:999";
+    const args = ["run", "--detach", "--name", name, ...labelArgs(labels), "--network", resources.network, "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", ...securityOptions, "--user", serviceUser, "--init", "--stop-timeout", "10", "--pids-limit", "256", "--memory", "1g", "--memory-swap", "1g", "--cpus", "1", "--tmpfs", "/tmp:rw,nosuid,nodev,size=256m", "--log-driver", "none"];
+    if (service.type === "postgres") {
+        args.push("--env", "POSTGRES_PASSWORD_FILE=/run/secrets/postgres-password", "--env", "POSTGRES_USER=forge", "--env", "POSTGRES_DB=forge_test", "--volume", `${resources.secretsVolume}:/run/secrets:ro`, "--tmpfs", "/var/lib/postgresql/data:rw,nosuid,nodev,size=1g", "--health-cmd", "pg_isready -U forge -d forge_test", "--health-interval", "1s", "--health-timeout", "5s", "--health-retries", "60");
+    }
+    else if (service.type === "redis") {
+        args.push("--volume", `${resources.secretsVolume}:/run/secrets:ro`, "--health-cmd", "redis-cli -a \"$(cat /run/secrets/redis-password)\" ping", "--health-interval", "1s", "--health-timeout", "5s", "--health-retries", "60", "--entrypoint", "/bin/sh");
+    }
+    else {
+        const healthCommand = environment.FORGE_SERVICE_BROWSER_HEALTH_CMD?.trim();
+        if (!healthCommand || /[\r\n\0]/u.test(healthCommand) || healthCommand.length > 1000) {
+            throw new Error("sandbox_service_health_policy_invalid: browser service needs an operator-configured bounded health command.");
+        }
+        args.push("--env", "FORGE_BROWSER_TOKEN_FILE=/run/secrets/browser-token", "--volume", `${resources.secretsVolume}:/run/secrets:ro`, "--health-cmd", healthCommand, "--health-interval", "1s", "--health-timeout", "5s", "--health-retries", "60");
+    }
+    args.push(image);
+    if (service.type === "redis")
+        args.push("-c", "exec redis-server --requirepass \"$(cat /run/secrets/redis-password)\"");
+    return args;
+}
+export function resolveSandboxSecurityOptions(executionPolicy, environment = process.env) {
+    const seccomp = environment.FORGE_SANDBOX_SECCOMP_PROFILE?.trim();
+    const lsm = environment.FORGE_SANDBOX_LSM_SECURITY_OPT?.trim();
+    if (seccomp && (!path.isAbsolute(seccomp) || /[\r\n\0]/u.test(seccomp))) {
+        throw new Error("sandbox_security_profile_invalid: seccomp profile must be an absolute host path.");
+    }
+    if (lsm && !/^(?:apparmor=[a-zA-Z0-9_.-]{1,128}|label=[a-zA-Z0-9_:,.-]{1,256})$/u.test(lsm)) {
+        throw new Error("sandbox_security_profile_invalid: LSM security option is invalid.");
+    }
+    if (executionPolicy === "sandbox_required" && (!seccomp || !lsm)) {
+        throw new Error("sandbox_security_profile_unavailable: sandbox_required needs explicit seccomp and LSM profiles.");
+    }
+    return [
+        ...(seccomp ? ["--security-opt", `seccomp=${seccomp}`] : []),
+        ...(lsm ? ["--security-opt", lsm] : [])
+    ];
+}
+export function networkCreateArgs(dispatch, environment = process.env) {
+    const policy = dispatch.sandbox.networkPolicy;
+    if (policy.mode === "open_public") {
+        if (dispatch.sandbox.executionPolicy === "sandbox_required" || environment.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX !== "true") {
+            throw new Error("policy_mismatch: open_public sandbox networking is not permitted by this runner policy.");
+        }
+        return [];
+    }
+    if (policy.mode === "public_allowlist" && policy.allowedHosts.length > 0) {
+        if (environment.FORGE_SANDBOX_EGRESS_ENFORCED !== "true") {
+            throw new Error("policy_mismatch: public_allowlist requires an operator-enforced Forge egress proxy or firewall.");
+        }
+        return ["--internal"];
+    }
+    return ["--internal"];
+}
+function withSandboxMetadata(dispatch, input, config, contract, image) { return { ...dispatch, repo: { ...dispatch.repo, serverLocalPath: null, remoteUrl: "/control/input/repo.bundle", cloneOnDemand: true }, serverLocal: { repoRoot: "/workspace", cleanupWorktrees: false }, sandbox: { ...dispatch.sandbox, inputCommitSha: input, sandboxConfigCommitSha: config, contractDigest: contract, imageDigest: image } }; }
+function serviceImage(type) { const key = `FORGE_SERVICE_${type.toUpperCase()}_IMAGE`; const image = process.env[key]; return image?.includes("@sha256:") ? image : null; }
+function event(eventType, content, data) {
+    return {
+        role: "runner",
+        kind: /(?:failed|timeout|expired|exhausted|killed|rejected|invalid|unavailable|limit)/iu.test(eventType) ? "error" : "checkpoint",
+        content,
+        eventType,
+        occurredAt: new Date().toISOString(),
+        data: data ? JSON.stringify(data) : null
+    };
+}
+export function classifySandboxRuntimeFailure(value) {
+    const message = value.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 2000) || "Sandbox execution failed.";
+    const explicit = /^([a-z][a-z0-9_.-]{2,79}):/u.exec(message)?.[1] ?? null;
+    let code = explicit ?? "sandbox_runtime_failed";
+    if (/no space left|disk quota exceeded|enospc/iu.test(message))
+        code = "sandbox_storage_exhausted";
+    const phase = code.startsWith("sandbox_build") || code.startsWith("image_") ? "build"
+        : code.startsWith("sandbox_output") || code.startsWith("sandbox_import") ? "import"
+            : code.startsWith("teardown") ? "teardown"
+                : code.startsWith("sandbox_config") || code.startsWith("sandbox_auth") || code.startsWith("contract_") || code.startsWith("sandbox_input") || code.startsWith("sandbox_create") ? "prepare"
+                    : "agent";
+    return { code, phase, message };
+}
+export function classifySandboxResourceFailure(value) {
+    const diagnostic = value.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 2000);
+    if (!diagnostic)
+        return null;
+    if (/(?:oomkilled|out of memory|memory cgroup out of memory|cannot allocate memory)/iu.test(diagnostic)) {
+        return { code: "sandbox_oom_killed", message: "Sandbox exceeded its memory limit." };
+    }
+    if (/(?:resource temporarily unavailable|cannot fork|fork:\s*(?:retry|resource)|pthread_create[^.]*resource|process limit|pids? limit)/iu.test(diagnostic)) {
+        return { code: "sandbox_pid_exhausted", message: "Sandbox exceeded its process/PID limit." };
+    }
+    if (/(?:no space left on device|disk quota exceeded|\benospc\b|workspace quota|storage limit)/iu.test(diagnostic)) {
+        return { code: "sandbox_storage_exhausted", message: "Sandbox exceeded its workspace/storage limit." };
+    }
+    if (/(?:too many open files|\bemfile\b|\benfile\b)/iu.test(diagnostic)) {
+        return { code: "sandbox_file_descriptor_exhausted", message: "Sandbox exceeded its file-descriptor limit." };
+    }
+    return null;
+}
+function parseSandboxEventLine(line) {
+    if (!line.trim().startsWith("{"))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object" || value.type !== "runner_event")
+        return null;
+    const candidate = value.event;
+    if (!candidate || typeof candidate !== "object")
+        throw new Error("sandbox_event_invalid: runner event envelope is missing event data.");
+    const eventValue = candidate;
+    for (const field of ["role", "kind", "content", "eventType"]) {
+        if (typeof eventValue[field] !== "string")
+            throw new Error(`sandbox_event_invalid: ${field} must be a string.`);
+    }
+    if (eventValue.role.length > 64
+        || eventValue.kind.length > 128
+        || eventValue.eventType.length > 128
+        || Buffer.byteLength(eventValue.content, "utf8") > 256 * 1024) {
+        throw new Error("sandbox_event_invalid: runner event exceeds field bounds.");
+    }
+    if (eventValue.data !== undefined && eventValue.data !== null
+        && (typeof eventValue.data !== "string" || Buffer.byteLength(eventValue.data, "utf8") > 256 * 1024)) {
+        throw new Error("sandbox_event_invalid: runner event data exceeds field bounds.");
+    }
+    if (eventValue.occurredAt !== undefined && eventValue.occurredAt !== null
+        && (typeof eventValue.occurredAt !== "string" || !Number.isFinite(Date.parse(eventValue.occurredAt)))) {
+        throw new Error("sandbox_event_invalid: runner event occurredAt is invalid.");
+    }
+    return {
+        role: eventValue.role,
+        kind: eventValue.kind,
+        content: eventValue.content,
+        eventType: eventValue.eventType,
+        occurredAt: eventValue.occurredAt,
+        data: eventValue.data
+    };
+}