@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.1ff37038366e

package/dist/sandbox/runtime.js

@@ -2,7 +2,7 @@ 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 { createFailureEnvelope, ForgeFailureError, failureFactsForCode, failurePolicyForCode, failureResult, parseRunOnceResultPacket, } from "../session/session.types.js";
 import { dockerfileUpstreamImages, validateDockerfilePolicy, validateSandboxContract } from "./contract.js";
 import { requireSandboxProcess, runSandboxProcess } from "./process.js";
 import { createLeaseUpdate } from "./lease-watchdog.js";
@@ -85,7 +85,7 @@ export class DockerSandboxRuntime {
             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.");
+                throw trustedSandboxFailure("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);
@@ -100,7 +100,7 @@ export class DockerSandboxRuntime {
             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}`);
+                throw trustedSandboxFailure("sandbox_auth_unavailable", providerAuthUnavailable);
             }
             await sink.emit(event("sandbox_metadata", "Resolved immutable sandbox inputs.", {
                 inputCommitSha: prepared.inputCommitSha,
@@ -125,6 +125,7 @@ export class DockerSandboxRuntime {
             await this.writeLedger(active.ledger);
             let teardownComplete = false;
             let memoryTelemetryEvent = null;
+            let trustedHostFailure = null;
             try {
                 const internalNetworkId = dockerObjectId((await this.docker(["network", "create", ...networkArgs, ...labelArgs(labels), resources.network], 30_000, runtimeSignal)).stdout, "network");
                 await this.docker(["volume", "create", ...labelArgs(labels), resources.workspaceVolume], 30_000, runtimeSignal);
@@ -217,19 +218,18 @@ export class DockerSandboxRuntime {
                     await sink.emit(memoryTelemetryEvent).catch(() => undefined);
                 });
                 if (start.truncated)
-                    throw new Error("sandbox_log_limit: sandbox output exceeded the 8 MiB supervisor capture budget.");
+                    throw trustedSandboxFailure("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.");
+                    trustedHostFailure = {
+                        code: "sandbox_oom_killed",
+                        message: "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}`);
+                if (start.exitCode !== 0 && !trustedHostFailure) {
+                    // Docker's inspect state is trusted host telemetry. Child stdout/stderr is
+                    // evidence only and must not be able to choose a machine failure code.
+                    trustedHostFailure = classifySandboxResourceFailure(containerState.error ?? "");
                 }
                 active.phase = "active";
                 await sink.emit(event("sandbox_agent_exited", `Sandbox worker exited with code ${start.exitCode}.`, {
@@ -250,7 +250,7 @@ export class DockerSandboxRuntime {
                 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.");
+                        throw trustedSandboxFailure("sandbox_output_publish_forbidden", "bridge publication grant redemption is unavailable.");
                     }
                     const credential = await this.publicationGrantRedeemer({
                         dispatchAttemptId: runtimeDispatch.sandbox.dispatchAttemptId,
@@ -269,29 +269,26 @@ export class DockerSandboxRuntime {
                         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 appendRunOnceEvent({
-                            ...result,
-                            summary: resourceFailure.message,
-                            events: [...result.events, event(resourceFailure.code, resourceFailure.message, { phase: "agent" })]
-                        }, memoryTelemetryEvent);
-                    }
-                }
+                const rawResult = parseRunOnceResultPacket(JSON.parse(await fs.readFile(output.resultPath, "utf8")));
+                const result = {
+                    ...rawResult,
+                    resultCommitSha: output.manifest.resultCommitSha ?? rawResult.resultCommitSha ?? null,
+                    publishedCommitSha: runtimeDispatch.sandbox.publicationMode === "bridge_push"
+                        ? output.manifest.resultCommitSha
+                        : rawResult.publishedCommitSha ?? null,
+                };
+                const canonicalResult = applyTrustedHostFailure(result, trustedHostFailure);
                 await sink.emit(event("sandbox_output_imported", "Validated and imported sandbox output.", {
                     resultCommitSha: output.manifest.resultCommitSha,
                 }));
-                return appendRunOnceEvent(result, memoryTelemetryEvent);
+                return appendRunOnceEvent(canonicalResult, memoryTelemetryEvent);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                const classified = classifySandboxRuntimeFailure(message);
-                return appendRunOnceEvent(failureResult(classified.message, [event(classified.code, classified.message, { phase: classified.phase })]), memoryTelemetryEvent);
+                const effectiveError = trustedHostFailure
+                    ? new ForgeFailureError(trustedHostFailure.code, trustedHostFailure.message, "sandbox", { cause: error })
+                    : error;
+                const classified = classifySandboxRuntimeFailure(effectiveError);
+                return appendRunOnceEvent(failureResult(classified.message, [event(classified.code, classified.message, { phase: classified.phase })], failureFactsForCode(classified.code, "sandbox")), memoryTelemetryEvent);
             }
             finally {
                 try {
@@ -525,7 +522,7 @@ export class DockerSandboxRuntime {
     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.");
+            throw trustedSandboxFailure("sandbox_identity_invalid", "dispatch attempt id must be a full UUID.");
         return path.join(this.config.sandboxStateRoot, "ledger", `${attemptHex}.json`);
     }
     async removeLedger(dispatchAttemptId) {
@@ -534,11 +531,11 @@ export class DockerSandboxRuntime {
     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.");
+            throw trustedSandboxFailure("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.");
+            throw trustedSandboxFailure("sandbox_build_failed", "invalid pinned Codex package version.");
         const policyConfigurationDigest = await sandboxImagePolicyConfigurationDigest();
         const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
         const bridgeRuntimeDigest = await bridgeRuntimeContentDigest(packageRoot);
@@ -631,7 +628,7 @@ export class DockerSandboxRuntime {
         }
         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.");
+            throw trustedSandboxFailure("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 }));
@@ -658,7 +655,7 @@ export class DockerSandboxRuntime {
         const installMode = await copyBridgePackageManifests(packageRoot, stagedBridgeRoot);
         const stagedBridgeRuntimeDigest = await bridgeRuntimeContentDigest(stagedBridgeRoot);
         if (stagedBridgeRuntimeDigest !== bridgeRuntimeDigest) {
-            throw new Error("sandbox_build_failed: bridge runtime payload changed while preparing the sandbox image; retry the dispatch.");
+            throw trustedSandboxFailure("sandbox_build_failed", "bridge runtime payload changed while preparing the sandbox image; retry the dispatch.");
         }
         const dockerfile = agentOverlayDockerfile(toolingImage, projectContextName, installMode, codexVersion);
         await fs.writeFile(path.join(overlayRoot, "Dockerfile"), dockerfile);
@@ -666,7 +663,7 @@ export class DockerSandboxRuntime {
         await this.runBuildStage("tooling", key, buildxBuildArgs(builder, path.join(metadataRoot, "tooling.json"), ["--pull=false", "--target", "tooling", ...imageLabelArgs(project, key, "tooling", bridgeRuntimeDigest), "--tag", helperTag, overlayRoot]), sink, signal);
         const helperImageDigest = (await this.docker(["image", "inspect", helperTag, "--format", "{{.Id}}"], 15_000)).stdout.trim();
         if (!/^sha256:[0-9a-f]{64}$/i.test(helperImageDigest))
-            throw new Error("sandbox_build_failed: helper image did not resolve to an immutable digest.");
+            throw trustedSandboxFailure("sandbox_build_failed", "helper image did not resolve to an immutable digest.");
         const projectContextRef = ociLayoutContextRef(path.relative(overlayRoot, projectOciRoot));
         await this.runBuildStage("agent", key, buildxBuildArgs(builder, path.join(metadataRoot, "agent.json"), [
             "--pull=false",
@@ -677,7 +674,7 @@ export class DockerSandboxRuntime {
         ]), sink, signal, { cwd: overlayRoot });
         const digest = (await this.docker(["image", "inspect", overlayTag, "--format", "{{.Id}}"], 15_000)).stdout.trim();
         if (!/^sha256:[0-9a-f]{64}$/i.test(digest))
-            throw new Error("sandbox_build_failed: overlay image did not resolve to an immutable digest.");
+            throw trustedSandboxFailure("sandbox_build_failed", "overlay image did not resolve to an immutable digest.");
         const imagePolicy = await evaluateSandboxImagePolicy({
             key,
             project: dockerLabelValue(project),
@@ -752,7 +749,7 @@ export class DockerSandboxRuntime {
             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}.`);
+        throw trustedSandboxFailure("sandbox_build_failed", `${stage} image build failed; restricted log digest ${artifact.digest}.`);
     }
     async ensureBuildxBuilder(signal) {
         const name = dedicatedBuildxBuilderName(this.config.runnerId, this.config.dockerContext);
@@ -775,7 +772,7 @@ export class DockerSandboxRuntime {
         if (Number(hostConfig.PidsLimit) !== policy.builderPidsLimit
             || Number(hostConfig.Memory) !== policy.builderMemoryBytes
             || Number(hostConfig.MemorySwap) !== policy.builderMemoryBytes) {
-            throw new Error("sandbox_build_policy_failed: dedicated BuildKit builder resource limits were not applied.");
+            throw trustedSandboxFailure("sandbox_build_policy_failed", "dedicated BuildKit builder resource limits were not applied.");
         }
         return name;
     }
@@ -848,10 +845,10 @@ export class DockerSandboxRuntime {
             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.");
+            throw trustedSandboxFailure("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.");
+            throw trustedSandboxFailure("sandbox_egress_proxy_unavailable", "runner egress enforcement is not enabled.");
         }
         await this.verifyCatalogImage(image, dispatch.sandbox.executionPolicy, sink, signal);
         const name = `${resources.prefix}-egress`;
@@ -1162,7 +1159,7 @@ class HostGit {
                 || !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.");
+                throw trustedSandboxFailure("sandbox_output_publish_forbidden", "remote publication grant is missing or outside its attempt scope.");
             }
             assertCurrent();
             const credentialEnvironment = publicationCredentialEnvironment(credential);
@@ -1202,15 +1199,15 @@ class HostGit {
                 terminateOnOutputLimit: true
             });
             if (objectInventory.exitCode !== 0 || objectInventory.truncated) {
-                throw new Error("sandbox_output_invalid: Git bundle exceeds object validation limits.");
+                throw trustedSandboxFailure("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.");
+                throw trustedSandboxFailure("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.");
+                throw trustedSandboxFailure("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);
@@ -1238,7 +1235,7 @@ class HostGit {
         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.");
+            throw trustedSandboxFailure("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 });
     }
@@ -1249,7 +1246,7 @@ class HostGit {
             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.");
+        throw trustedSandboxFailure("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 }); }
 }
@@ -1259,19 +1256,19 @@ export function managedBranchUpdateExpectedValue(current, expectedInput, importe
         return "0".repeat(imported.length);
     }
     if (normalized !== expectedInput) {
-        throw new Error("sandbox_output_conflict: managed branch changed after sandbox input was captured.");
+        throw trustedSandboxFailure("sandbox_output_conflict", "managed branch changed after sandbox input was captured.");
     }
     return normalized;
 }
 export function publicationPushArgs(branch, resultCommitSha, inputCommitSha, remoteCommitSha, remote = "origin") {
     const isCommit = (value) => /^[0-9a-f]{40,64}$/iu.test(value);
     if (!branch || branch.length > 240 || !isCommit(resultCommitSha) || !isCommit(inputCommitSha) || (remoteCommitSha && !isCommit(remoteCommitSha))) {
-        throw new Error("sandbox_output_publish_rejected: publication inputs contain an invalid branch or object id.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("sandbox_output_publish_stale", "remote branch changed after the sandbox input was captured.");
     }
     const remoteRef = `refs/heads/${branch}`;
     return [
@@ -1303,7 +1300,7 @@ export function validatePublicationCredential(credential, nowMs = Date.now()) {
         || 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.");
+        throw trustedSandboxFailure("sandbox_output_publish_forbidden", "redeemed publication credential is invalid or expired.");
     }
 }
 export function publicationCredentialEnvironment(credential, environment = process.env) {
@@ -1333,7 +1330,7 @@ export function restrictedBuildLog(source, exactSecrets = [], maximumBytes = 4 *
 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.");
+        throw trustedSandboxFailure("sandbox_output_invalid", "Git bundle exceeds the object-count budget.");
     }
     const maximum = BigInt(maximumExpandedBytes);
     let expanded = 0n;
@@ -1341,13 +1338,13 @@ export function validateGitObjectBudget(inventory, maximumObjectCount = 500_000,
     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.");
+            throw trustedSandboxFailure("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.");
+            throw trustedSandboxFailure("sandbox_output_invalid", "Git bundle exceeds the expanded-object byte budget.");
         }
     }
     return { objectCount: lines.length, expandedBytes: Number(expanded) };
@@ -1355,11 +1352,11 @@ export function validateGitObjectBudget(inventory, maximumObjectCount = 500_000,
 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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("sandbox_output_invalid", "Git result exceeds the commit-depth budget.");
     }
     return Number(depth);
 }
@@ -1375,10 +1372,10 @@ export function selectAuditArtifactGcCandidates(records, retentionCount, retenti
 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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("sandbox_config_commit_invalid", "approved sandbox config commit is not a full Git object id.");
     }
     return approvedSha
         ? { refs: [approvedSha], approvedSha }
@@ -1423,12 +1420,12 @@ async function validateOutput(attemptRoot, dispatch) {
     const manifestPath = path.join(outputRoot, "manifest.json");
     const stat = await fs.lstat(manifestPath).catch(error => {
         if (isNodeErrorWithCode(error, "ENOENT")) {
-            throw new Error("sandbox_output_missing: sandbox worker did not produce manifest.json.");
+            throw trustedSandboxFailure("sandbox_output_missing", "sandbox worker did not produce manifest.json.");
         }
         throw error;
     });
     if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
-        throw new Error("sandbox_output_invalid: manifest must be a bounded regular file.");
+        throw trustedSandboxFailure("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
@@ -1439,10 +1436,10 @@ async function validateOutput(attemptRoot, dispatch) {
         || 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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("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;
@@ -1450,14 +1447,14 @@ async function validateOutput(attemptRoot, dispatch) {
 }
 async function validateManifestFile(root, file, max) {
     if (!/^[a-z0-9_.-]+$/i.test(file.path))
-        throw new Error("sandbox_output_invalid: output path is invalid.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("sandbox_output_invalid", "output hash mismatch.");
     return target;
 }
 function isMissingSandboxManifest(error) {
@@ -1479,7 +1476,7 @@ export function sandboxWorkerFailureMessage(exitCode, stderr, containerError) {
 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.");
+        throw trustedSandboxFailure("sandbox_identity_invalid", "dispatch attempt id must be a full UUID.");
     return { attemptHex: value };
 }
 class SandboxTeardownError extends Error {
@@ -1688,7 +1685,7 @@ export function assertSandboxImportCurrent(expected, current, signal, nowMs = Da
         || 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.");
+        throw trustedSandboxFailure("sandbox_output_stale", "output cannot move the managed ref because its attempt, fence, or lease is no longer current.");
     }
 }
 export function validSandboxLedger(value) {
@@ -1830,7 +1827,7 @@ export function sandboxResourceLabels(dispatch, image, contract) {
     ];
     const invalid = ownershipIds.find(([, value]) => !isFullUuid(value));
     if (invalid)
-        throw new Error(`sandbox_identity_invalid: ${invalid[0]} id must be a full UUID.`);
+        throw trustedSandboxFailure("sandbox_identity_invalid", `${invalid[0]} id must be a full UUID.`);
     return {
         "dev.forge.managed": "true", "dev.forge.session-id": dispatch.session.id, "dev.forge.resource-lease-id": resourceLeaseId, "dev.forge.execution-lease-id": resourceLeaseId,
         "dev.forge.dispatch-attempt-id": dispatch.sandbox.dispatchAttemptId, "dev.forge.fencing-token": dispatch.lease.fencingToken,
@@ -1919,13 +1916,13 @@ export async function extractOciLayoutArchive(archivePath, destination, signal)
         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}.`);
+        throw trustedSandboxFailure("sandbox_build_failed", `project OCI layout extraction failed with exit code ${result.exitCode}; ${formatOciExtractionFailure(result)}. Archive retained at ${archivePath}.`);
     }
     await fs.rm(archivePath, { force: true }).catch(() => undefined);
 }
 export function ociLayoutContextRef(layoutPath) {
     if (/^[A-Za-z]:[\\/]/u.test(layoutPath)) {
-        throw new Error("sandbox_build_failed: Windows absolute OCI layout paths are not BuildKit-safe; use a relative path from the build working directory.");
+        throw trustedSandboxFailure("sandbox_build_failed", "Windows absolute OCI layout paths are not BuildKit-safe; use a relative path from the build working directory.");
     }
     const normalized = layoutPath.replace(/\\/gu, "/").replace(/^\.\//u, "");
     // BuildKit's oci-layout resolver expects a raw filesystem path here; it does not percent-decode
@@ -1945,7 +1942,7 @@ export async function readOciLayoutImageDigest(layoutRoot) {
         && /^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.");
+        throw trustedSandboxFailure("sandbox_build_failed", "project OCI layout did not expose an immutable image digest.");
     }
     return manifest.digest;
 }
@@ -1980,11 +1977,11 @@ export async function bridgeRuntimeContentDigest(packageRoot) {
     const distRoot = path.join(root, "dist");
     const distStat = await fs.lstat(distRoot).catch(() => null);
     if (!distStat?.isDirectory() || distStat.isSymbolicLink()) {
-        throw new Error("sandbox_build_failed: bridge runtime dist must be a real directory.");
+        throw trustedSandboxFailure("sandbox_build_failed", "bridge runtime dist must be a real directory.");
     }
     const distFiles = await collectBridgeRuntimeFiles(root, "dist");
     if (distFiles.length === 0) {
-        throw new Error("sandbox_build_failed: bridge runtime dist is empty.");
+        throw trustedSandboxFailure("sandbox_build_failed", "bridge runtime dist is empty.");
     }
     const files = [packageManifest, ...(lockManifest ? [lockManifest] : []), ...distFiles]
         .sort((left, right) => compareBridgeRuntimePaths(left.relativePath, right.relativePath));
@@ -2003,7 +2000,7 @@ export async function bridgeRuntimeContentDigest(packageRoot) {
 async function requireBridgeRuntimeFile(root, relativePath) {
     const file = await optionalBridgeRuntimeFile(root, relativePath);
     if (!file)
-        throw new Error(`sandbox_build_failed: bridge runtime ${relativePath} is missing.`);
+        throw trustedSandboxFailure("sandbox_build_failed", `bridge runtime ${relativePath} is missing.`);
     return file;
 }
 async function optionalBridgeRuntimeFile(root, relativePath) {
@@ -2012,7 +2009,7 @@ async function optionalBridgeRuntimeFile(root, relativePath) {
     if (!stat)
         return null;
     if (!stat.isFile() || stat.isSymbolicLink()) {
-        throw new Error(`sandbox_build_failed: bridge runtime ${relativePath} must be a regular file.`);
+        throw trustedSandboxFailure("sandbox_build_failed", `bridge runtime ${relativePath} must be a regular file.`);
     }
     return { absolutePath, relativePath: relativePath.replace(/\\/gu, "/") };
 }
@@ -2024,14 +2021,14 @@ async function collectBridgeRuntimeFiles(root, relativeDirectory) {
     for (const entry of entries) {
         const relativePath = path.join(relativeDirectory, entry.name);
         if (entry.isSymbolicLink()) {
-            throw new Error(`sandbox_build_failed: bridge runtime ${relativePath.replace(/\\/gu, "/")} cannot be a symbolic link.`);
+            throw trustedSandboxFailure("sandbox_build_failed", `bridge runtime ${relativePath.replace(/\\/gu, "/")} cannot be a symbolic link.`);
         }
         if (entry.isDirectory()) {
             files.push(...await collectBridgeRuntimeFiles(root, relativePath));
             continue;
         }
         if (!entry.isFile()) {
-            throw new Error(`sandbox_build_failed: bridge runtime ${relativePath.replace(/\\/gu, "/")} must be a regular file.`);
+            throw trustedSandboxFailure("sandbox_build_failed", `bridge runtime ${relativePath.replace(/\\/gu, "/")} must be a regular file.`);
         }
         files.push({
             absolutePath: path.join(root, relativePath),
@@ -2086,7 +2083,7 @@ async function copyOptionalBridgeManifest(packageRoot, bridgeRoot, fileName) {
 }
 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.");
+        throw trustedSandboxFailure("sandbox_build_failed", "invalid dedicated builder name.");
     const resources = buildResourcePolicy(environment);
     const args = ["buildx", "build", "--builder", builder];
     if (options.load !== false)
@@ -2108,7 +2105,7 @@ export function dedicatedBuildxBuilderName(runnerId, dockerContext) {
 }
 export function dedicatedBuildxBuilderContainerName(builder) {
     if (!/^forge-[0-9a-f]{20}$/u.test(builder))
-        throw new Error("sandbox_build_failed: invalid dedicated builder name.");
+        throw trustedSandboxFailure("sandbox_build_failed", "invalid dedicated builder name.");
     return `buildx_buildkit_${builder}0`;
 }
 function boundedBuildCacheSize(value, fallback) {
@@ -2132,7 +2129,7 @@ export function selectImageGcCandidates(records, keepPerProject, ttlMs, nowMs) {
 async function sandboxProviderAuthForDispatch(dispatch) {
     const unavailable = sandboxProviderAuthUnavailableMessage(dispatch.execution.provider, dispatch.execution.authKind);
     if (unavailable) {
-        throw new Error(`sandbox_auth_unavailable: ${unavailable}`);
+        throw trustedSandboxFailure("sandbox_auth_unavailable", unavailable);
     }
     const adapter = sandboxProviderAuthAdapterFor(dispatch.execution.provider, dispatch.execution.authKind);
     return adapter ? adapter.prepareAttemptAuth() : null;
@@ -2176,7 +2173,7 @@ export function proxyEnvironmentArgs(dispatch, contract, resources) {
 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.");
+        throw trustedSandboxFailure("sandbox_egress_policy_invalid", "public_allowlist requires at least one approved host.");
     return [
         "http_port 3128",
         "access_log none",
@@ -2208,7 +2205,7 @@ export function serviceContainerArgs(service, image, resources, labels, security
     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.");
+            throw trustedSandboxFailure("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");
     }
@@ -2221,13 +2218,13 @@ export function resolveSandboxSecurityOptions(executionPolicy, environment = pro
     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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("sandbox_security_profile_unavailable", "sandbox_required needs explicit seccomp and LSM profiles.");
     }
     return [
         ...(seccomp ? ["--security-opt", `seccomp=${seccomp}`] : []),
@@ -2263,17 +2260,46 @@ function event(eventType, content, data) {
     };
 }
 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 };
+    const message = (value instanceof Error ? value.message : String(value))
+        .replace(/[\r\n\t]+/gu, " ")
+        .trim()
+        .slice(0, 2000) || "Sandbox execution failed.";
+    const code = value instanceof ForgeFailureError
+        ? value.failureCode
+        : "sandbox_runtime_failed";
+    return { code, phase: failurePolicyForCode(code).phase, message };
+}
+export function applyTrustedHostFailure(result, trustedFailure) {
+    if (!trustedFailure)
+        return result;
+    const originalFailure = result.failure
+        ? [{
+                code: result.failure.code,
+                message: result.failure.message,
+                source: result.failure.source,
+            }, ...result.failure.causalChain]
+        : result.exitCode === 0
+            ? []
+            : [{
+                    code: "sandbox_child_result_unknown",
+                    message: result.summary,
+                    source: "sandbox",
+                }];
+    const facts = {
+        ...failureFactsForCode(trustedFailure.code, "sandbox"),
+        causalChain: originalFailure,
+    };
+    return {
+        ...result,
+        schemaVersion: 2,
+        exitCode: result.exitCode === 0 ? 1 : result.exitCode,
+        summary: trustedFailure.message,
+        failure: createFailureEnvelope(trustedFailure.message, facts),
+        events: [
+            ...result.events,
+            event(trustedFailure.code, trustedFailure.message, { phase: facts.phase }),
+        ],
+    };
 }
 export function classifySandboxResourceFailure(value) {
     const diagnostic = value.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 2000);
@@ -2293,6 +2319,9 @@ export function classifySandboxResourceFailure(value) {
     }
     return null;
 }
+function trustedSandboxFailure(code, detail, options) {
+    return new ForgeFailureError(code, `${code}: ${detail}`, "sandbox", options);
+}
 function parseSandboxEventLine(line) {
     if (!line.trim().startsWith("{"))
         return null;
@@ -2307,25 +2336,25 @@ function parseSandboxEventLine(line) {
         return null;
     const candidate = value.event;
     if (!candidate || typeof candidate !== "object")
-        throw new Error("sandbox_event_invalid: runner event envelope is missing event data.");
+        throw trustedSandboxFailure("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.`);
+            throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("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.");
+        throw trustedSandboxFailure("sandbox_event_invalid", "runner event occurredAt is invalid.");
     }
     return {
         role: eventValue.role,