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

package/dist/sandbox/sandbox.types.d.ts

@@ -0,0 +1,93 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+export interface SandboxContract {
+    readonly schemaVersion: 1;
+    readonly workingDirectory: "/workspace";
+    readonly commands: Readonly<Record<string, string>>;
+    readonly caches: readonly SandboxCache[];
+    readonly services: readonly SandboxService[];
+    readonly environment: readonly string[];
+    readonly artifacts: readonly string[];
+    readonly logs: readonly string[];
+    readonly browser: boolean;
+}
+export interface SandboxCache {
+    readonly name: string;
+    readonly mode: "readonly" | "per_attempt";
+}
+export interface SandboxService {
+    readonly type: "postgres" | "redis" | "browser";
+    readonly port: number;
+}
+export interface ValidatedSandboxContract {
+    readonly contract: SandboxContract;
+    readonly normalizedJson: string;
+    readonly digest: string;
+}
+export interface SandboxPreflightResult {
+    readonly available: boolean;
+    readonly healthy: boolean;
+    readonly generation: number;
+    readonly sampledAt: string;
+    readonly runtimeVersion: string | null;
+    readonly maxConcurrentSandboxes: number;
+    readonly totalMemoryBytes: number;
+    /** Raw free memory reported by the host operating system. */
+    readonly rawHostAvailableMemoryBytes: number;
+    /** Raw free memory in Docker's capacity domain; null when that domain cannot be sampled. */
+    readonly rawDaemonAvailableMemoryBytes: number | null;
+    /** Conservative raw admission bound selected from every required memory domain. */
+    readonly rawAvailableMemoryBytes: number;
+    readonly availableMemoryBytes: number;
+    readonly hostReserveBytes: number;
+    readonly admissionMemoryBytes: number;
+    readonly availableCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+    readonly diskLow: boolean;
+    readonly unavailableCode: string | null;
+    readonly unavailableReason: string | null;
+    readonly features: SandboxFeatureMatrix;
+}
+export interface SandboxFeatureMatrix {
+    readonly rootless: boolean;
+    readonly userNamespaces: boolean;
+    readonly cgroupV2: boolean;
+    readonly seccomp: boolean;
+    readonly lsm: boolean;
+    readonly storageQuota: boolean;
+    readonly storagePolicy: boolean;
+    readonly compose: boolean;
+    readonly internalNetwork: boolean;
+    readonly buildkit: boolean;
+    readonly imagePolicy: boolean;
+    readonly securityProfile: boolean;
+    readonly egressProxy: boolean;
+}
+export interface SandboxReservation {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly expiresAt: string;
+    readonly reservedUntil: string;
+    readonly dispatch: RunOnceDispatchPacket;
+    readonly contract?: ValidatedSandboxContract;
+    readonly inputCommitSha?: string;
+    readonly sandboxConfigCommitSha?: string;
+    readonly imageDigest?: string;
+}
+export interface CommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandRunner {
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}
+export interface CommandOptions {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly stdin?: string | Uint8Array;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly maxOutputBytes?: number;
+}

package/dist/sandbox/sandbox.types.js

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/smoke.d.ts

@@ -0,0 +1,76 @@
+import type { BridgeServiceConfig } from "../bridge/bridge.types.js";
+import type { CommandRunner } from "./sandbox.types.js";
+export interface SandboxSmokeRequest {
+    readonly repoPath: string;
+    readonly reportPath?: string;
+    readonly requirePinnedBase?: boolean;
+    readonly probeLoopbackPort?: boolean;
+    readonly onProgress?: (message: string) => void;
+}
+export interface SandboxSmokeStage {
+    readonly name: string;
+    readonly status: "passed" | "failed";
+    readonly durationMs: number;
+}
+export interface SandboxSmokeReport {
+    readonly schemaVersion: 1;
+    readonly kind: "forge_sandbox_smoke";
+    readonly status: "passed" | "failed";
+    readonly startedAt: string;
+    readonly completedAt: string;
+    readonly dispatchAttemptId: string;
+    readonly resourceLeaseId: string;
+    readonly repository: {
+        readonly name: string;
+        readonly contractDigest: string | null;
+        readonly dockerfileDigest: string | null;
+        readonly policyWarnings: readonly string[];
+    };
+    readonly docker: {
+        readonly runtimeVersion: string | null;
+        readonly contextConfigured: boolean;
+        readonly capacity: number;
+        readonly availableMemoryBytes: number;
+        readonly availableCpuMillis: number;
+        readonly availableWorkspaceBytes: number;
+    };
+    readonly publishedPortProbe: {
+        readonly containerPort: number;
+        readonly hostIp: "127.0.0.1";
+        readonly hostPort: number;
+    } | null;
+    readonly stages: readonly SandboxSmokeStage[];
+    readonly cleanup: {
+        readonly verified: boolean;
+        readonly removed: readonly string[];
+        readonly residual: {
+            readonly containers: number;
+            readonly networks: number;
+            readonly volumes: number;
+            readonly images: number;
+        };
+    };
+    readonly failure: {
+        readonly code: string;
+        readonly stage: string;
+        readonly message: string;
+    } | null;
+}
+export interface SandboxSmokeResult {
+    readonly report: SandboxSmokeReport;
+    readonly reportPath: string;
+}
+export declare class DockerSandboxSmoke {
+    private readonly config;
+    private readonly commands;
+    constructor(config: BridgeServiceConfig, commands?: CommandRunner);
+    run(request: SandboxSmokeRequest): Promise<SandboxSmokeResult>;
+    private createPreflight;
+    private stage;
+    private labelArgs;
+    private dockerArgs;
+    private requireDocker;
+    private cleanup;
+    private inventoryCount;
+}
+export declare function parseDockerAssignedLoopbackPort(output: string): SandboxSmokeReport["publishedPortProbe"];

package/dist/sandbox/smoke.js

@@ -0,0 +1,380 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets } from "../shared/redaction/redaction.js";
+import { BoundedCommandRunner } from "./command-runner.js";
+import { validateDockerfilePolicy, validateSandboxContract } from "./contract.js";
+import { DockerPreflight } from "./preflight.js";
+const managedLabel = "dev.forge.managed";
+const smokeLabel = "dev.forge.smoke";
+const attemptLabel = "dev.forge.dispatch-attempt-id";
+const resourceLeaseLabel = "dev.forge.resource-lease-id";
+export class DockerSandboxSmoke {
+    config;
+    commands;
+    constructor(config, commands = new BoundedCommandRunner()) {
+        this.config = config;
+        this.commands = commands;
+    }
+    async run(request) {
+        const startedAt = new Date();
+        const dispatchAttemptId = randomUUID();
+        const resourceLeaseId = randomUUID();
+        const token = dispatchAttemptId.replaceAll("-", "").slice(0, 20);
+        const resources = {
+            image: `forge-sandbox-smoke:${token}`,
+            container: `forge-smoke-agent-${token}`,
+            network: `forge-smoke-network-${token}`,
+            volume: `forge-smoke-workspace-${token}`,
+            portFixtureContainer: `forge-smoke-port-${token}`,
+            portFixtureNetwork: `forge-smoke-port-network-${token}`,
+        };
+        const reportPath = path.resolve(request.reportPath ?? path.join(this.config.sandboxStateRoot, "smoke-reports", `${startedAt.toISOString().replaceAll(":", "-")}-${token}.json`));
+        const evidence = {
+            contractDigest: null,
+            dockerfileDigest: null,
+            policyWarnings: [],
+            preflight: null,
+            stages: [],
+            removed: [],
+            residual: { containers: -1, networks: -1, volumes: -1, images: -1 },
+            cleanupVerified: false,
+            publishedPortProbe: null,
+            failure: null,
+        };
+        const preflight = this.createPreflight();
+        try {
+            await this.stage("doctor", evidence, request, async () => {
+                const forgePath = path.join(path.resolve(request.repoPath), ".forge");
+                const contractSource = await fs.readFile(path.join(forgePath, "forge.sandbox.yml"), "utf8");
+                const dockerfile = await fs.readFile(path.join(forgePath, "Dockerfile"), "utf8");
+                evidence.contractDigest = validateSandboxContract(contractSource).digest;
+                evidence.dockerfileDigest = `sha256:${createHash("sha256").update(dockerfile).digest("hex")}`;
+                evidence.policyWarnings = [...validateDockerfilePolicy(dockerfile, request.requirePinnedBase ?? false)];
+                evidence.preflight = await preflight.refresh();
+                if (!evidence.preflight.healthy) {
+                    throw new SmokeFailure(evidence.preflight.unavailableCode ?? "sandbox_preflight_failed", "doctor", evidence.preflight.unavailableReason ?? "Docker preflight did not report a healthy runtime.");
+                }
+            });
+            await this.stage("build_image", evidence, request, async () => {
+                const dockerfilePath = path.join(path.resolve(request.repoPath), ".forge", "Dockerfile");
+                await this.requireDocker("sandbox_smoke_build_failed", "build_image", [
+                    "build",
+                    "--tag", resources.image,
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    "--file", dockerfilePath,
+                    path.resolve(request.repoPath),
+                ], { timeoutMs: 15 * 60_000, maxOutputBytes: 64 * 1024 });
+            });
+            await this.stage("create_resources", evidence, request, async () => {
+                await this.requireDocker("sandbox_smoke_network_failed", "create_resources", [
+                    "network", "create", "--internal",
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    resources.network,
+                ]);
+                await this.requireDocker("sandbox_smoke_volume_failed", "create_resources", [
+                    "volume", "create",
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    resources.volume,
+                ]);
+                await this.requireDocker("sandbox_smoke_container_failed", "create_resources", [
+                    "create",
+                    "--name", resources.container,
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    "--network", resources.network,
+                    "--read-only",
+                    "--cap-drop", "ALL",
+                    "--security-opt", "no-new-privileges",
+                    "--pids-limit", "64",
+                    "--memory", String(256 * 1024 ** 2),
+                    "--memory-swap", String(256 * 1024 ** 2),
+                    "--cpus", "0.5",
+                    "--tmpfs", "/tmp:rw,nosuid,nodev,size=64m,uid=10001,gid=10001",
+                    "--user", "10001:10001",
+                    "--workdir", "/workspace",
+                    "--mount", `type=volume,src=${resources.volume},dst=/workspace,volume-nocopy`,
+                    "--env", `FORGE_SMOKE_ATTEMPT_ID=${dispatchAttemptId}`,
+                    "--env", `FORGE_RESOURCE_LEASE_ID=${resourceLeaseId}`,
+                    "--entrypoint", "/bin/sh",
+                    resources.image,
+                    "-lc",
+                    `set -eu; test "$PWD" = /workspace; test "$FORGE_SMOKE_ATTEMPT_ID" = "${dispatchAttemptId}"; test "$FORGE_RESOURCE_LEASE_ID" = "${resourceLeaseId}"; test ! -S /var/run/docker.sock; printf 'FORGE_SANDBOX_SMOKE_OK\\n'`,
+                ]);
+            });
+            await this.stage("verify_isolation", evidence, request, async () => {
+                const inspect = await this.requireDocker("sandbox_smoke_inspect_failed", "verify_isolation", [
+                    "inspect", "--format",
+                    "{{json .Mounts}}|{{.Config.User}}|{{.HostConfig.ReadonlyRootfs}}|{{.HostConfig.Privileged}}|{{json .HostConfig.CapDrop}}|{{json .HostConfig.PortBindings}}",
+                    resources.container,
+                ]);
+                const [mountsJson, user, readonlyRootfs, privileged, capDropJson, portBindingsJson] = inspect.stdout.trim().split("|");
+                const mounts = JSON.parse(mountsJson ?? "[]");
+                const capDrop = JSON.parse(capDropJson ?? "[]");
+                const workspaceMounted = mounts.some((mount) => mount.Destination === "/workspace" && mount.Name === resources.volume);
+                if (!workspaceMounted || user !== "10001:10001" || readonlyRootfs !== "true" || privileged !== "false"
+                    || !capDrop.includes("ALL") || !["null", "{}"].includes(portBindingsJson ?? "")) {
+                    throw new SmokeFailure("sandbox_smoke_isolation_failed", "verify_isolation", "The disposable container did not match the hardened smoke profile.");
+                }
+            });
+            await this.stage("execute", evidence, request, async () => {
+                const result = await this.requireDocker("sandbox_smoke_execution_failed", "execute", ["start", "--attach", resources.container]);
+                if (!result.stdout.includes("FORGE_SANDBOX_SMOKE_OK")) {
+                    throw new SmokeFailure("sandbox_smoke_marker_missing", "execute", "The disposable container exited without its success marker.");
+                }
+            });
+            if (request.probeLoopbackPort) {
+                await this.stage("discover_loopback_port", evidence, request, async () => {
+                    await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", [
+                        "network", "create",
+                        ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                        resources.portFixtureNetwork,
+                    ]);
+                    await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", [
+                        "create",
+                        "--name", resources.portFixtureContainer,
+                        ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                        "--network", resources.portFixtureNetwork,
+                        "--publish", "127.0.0.1::8080/tcp",
+                        "--read-only",
+                        "--cap-drop", "ALL",
+                        "--security-opt", "no-new-privileges",
+                        "--pids-limit", "32",
+                        "--memory", String(128 * 1024 ** 2),
+                        "--memory-swap", String(128 * 1024 ** 2),
+                        "--cpus", "0.25",
+                        "--tmpfs", "/tmp:rw,nosuid,nodev,size=16m,uid=10001,gid=10001",
+                        "--user", "10001:10001",
+                        "--entrypoint", "/bin/sh",
+                        resources.image,
+                        "-lc", "exec sleep 300",
+                    ]);
+                    await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", [
+                        "start", resources.portFixtureContainer,
+                    ]);
+                    const inspect = await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", ["inspect", "--format", "{{json .NetworkSettings.Ports}}", resources.portFixtureContainer]);
+                    evidence.publishedPortProbe = parseDockerAssignedLoopbackPort(inspect.stdout);
+                    if (!evidence.publishedPortProbe) {
+                        throw new SmokeFailure("sandbox_smoke_port_discovery_failed", "discover_loopback_port", "Docker did not assign exactly one valid loopback host port to the fixture.");
+                    }
+                });
+            }
+        }
+        catch (error) {
+            evidence.failure = failureFrom(error);
+        }
+        finally {
+            await this.cleanup(resources, dispatchAttemptId, evidence, request);
+            await preflight.release();
+        }
+        if (!evidence.cleanupVerified && !evidence.failure) {
+            evidence.failure = {
+                code: "sandbox_smoke_cleanup_failed",
+                stage: "cleanup",
+                message: "Exact-label cleanup verification found residual or unreadable Docker resources.",
+            };
+        }
+        const completedAt = new Date();
+        const report = redactSecrets({
+            schemaVersion: 1,
+            kind: "forge_sandbox_smoke",
+            status: evidence.failure || !evidence.cleanupVerified ? "failed" : "passed",
+            startedAt: startedAt.toISOString(),
+            completedAt: completedAt.toISOString(),
+            dispatchAttemptId,
+            resourceLeaseId,
+            repository: {
+                name: path.basename(path.resolve(request.repoPath)),
+                contractDigest: evidence.contractDigest,
+                dockerfileDigest: evidence.dockerfileDigest,
+                policyWarnings: evidence.policyWarnings,
+            },
+            docker: {
+                runtimeVersion: evidence.preflight?.runtimeVersion ?? null,
+                contextConfigured: this.config.dockerContext.length > 0,
+                capacity: evidence.preflight?.maxConcurrentSandboxes ?? 0,
+                availableMemoryBytes: evidence.preflight?.availableMemoryBytes ?? 0,
+                availableCpuMillis: evidence.preflight?.availableCpuMillis ?? 0,
+                availableWorkspaceBytes: evidence.preflight?.availableWorkspaceBytes ?? 0,
+            },
+            publishedPortProbe: evidence.publishedPortProbe,
+            stages: evidence.stages,
+            cleanup: {
+                verified: evidence.cleanupVerified,
+                removed: evidence.removed,
+                residual: evidence.residual,
+            },
+            failure: evidence.failure,
+        });
+        await writeReport(reportPath, report);
+        return { report, reportPath };
+    }
+    createPreflight() {
+        return new DockerPreflight({
+            dockerExecutable: this.config.dockerExecutable,
+            dockerContext: this.config.dockerContext,
+            stateRoot: this.config.sandboxStateRoot,
+            maxConcurrentSandboxes: this.config.maxConcurrentSandboxes,
+            diskHighWatermarkPercent: this.config.diskHighWatermarkPercent,
+            diskLowWatermarkPercent: this.config.diskLowWatermarkPercent,
+            minimumWorkspaceBytes: this.config.minimumWorkspaceBytes,
+            hostMemoryReserveBytes: this.config.sandboxHostMemoryReserveBytes,
+            defaultWorkerMemoryLimitBytes: this.config.defaultSandboxWorkerMemoryLimitBytes,
+            defaultServiceMemoryLimitBytes: this.config.defaultSandboxServiceMemoryLimitBytes,
+            runtimeOverheadBytes: this.config.sandboxRuntimeOverheadBytes,
+            requireRootless: this.config.requireRootlessDocker,
+        }, this.commands);
+    }
+    async stage(name, evidence, request, action) {
+        request.onProgress?.(name);
+        const started = Date.now();
+        try {
+            await action();
+            evidence.stages.push({ name, status: "passed", durationMs: Date.now() - started });
+        }
+        catch (error) {
+            evidence.stages.push({ name, status: "failed", durationMs: Date.now() - started });
+            if (error instanceof SmokeFailure)
+                throw error;
+            if (name === "doctor" && error instanceof Error && error.message.includes("docker_context_owned")) {
+                throw new SmokeFailure("sandbox_smoke_context_owned", name, "The Docker context is owned by a connected Forge bridge. Stop the bridge and retry.");
+            }
+            throw new SmokeFailure(`sandbox_smoke_${name}_failed`, name, name === "doctor"
+                ? "The repository contract, Dockerfile, or Docker preflight check failed."
+                : `The ${name.replaceAll("_", " ")} stage failed.`);
+        }
+    }
+    labelArgs(dispatchAttemptId, resourceLeaseId) {
+        return [
+            "--label", `${managedLabel}=true`,
+            "--label", `${smokeLabel}=true`,
+            "--label", `${attemptLabel}=${dispatchAttemptId}`,
+            "--label", `${resourceLeaseLabel}=${resourceLeaseId}`,
+        ];
+    }
+    dockerArgs(args) {
+        return this.config.dockerContext ? ["--context", this.config.dockerContext, ...args] : [...args];
+    }
+    async requireDocker(code, stage, args, options = {}) {
+        let result;
+        try {
+            result = await this.commands.run(this.config.dockerExecutable, this.dockerArgs(args), {
+                timeoutMs: options.timeoutMs ?? 60_000,
+                maxOutputBytes: options.maxOutputBytes ?? 16 * 1024,
+            });
+        }
+        catch {
+            throw new SmokeFailure(code, stage, "Docker could not execute the requested smoke stage.");
+        }
+        if (result.exitCode !== 0) {
+            throw new SmokeFailure(code, stage, `Docker exited with code ${result.exitCode} during the smoke stage.`);
+        }
+        return result;
+    }
+    async cleanup(resources, dispatchAttemptId, evidence, request) {
+        const started = Date.now();
+        request.onProgress?.("cleanup");
+        const removals = [
+            ["portFixtureContainer", ["rm", "--force", resources.portFixtureContainer]],
+            ["container", ["rm", "--force", resources.container]],
+            ["portFixtureNetwork", ["network", "rm", resources.portFixtureNetwork]],
+            ["network", ["network", "rm", resources.network]],
+            ["volume", ["volume", "rm", "--force", resources.volume]],
+            ["image", ["image", "rm", "--force", resources.image]],
+        ];
+        for (const [kind, args] of removals) {
+            try {
+                const result = await this.commands.run(this.config.dockerExecutable, this.dockerArgs(args), {
+                    timeoutMs: 60_000,
+                    maxOutputBytes: 8 * 1024,
+                });
+                if (result.exitCode === 0)
+                    evidence.removed.push(kind);
+            }
+            catch {
+                // Exact-label inventory below is authoritative for cleanup verification.
+            }
+        }
+        evidence.residual = {
+            containers: await this.inventoryCount(["ps", "--all", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+            networks: await this.inventoryCount(["network", "ls", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+            volumes: await this.inventoryCount(["volume", "ls", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+            images: await this.inventoryCount(["image", "ls", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+        };
+        evidence.cleanupVerified = Object.values(evidence.residual).every((count) => count === 0);
+        evidence.stages.push({
+            name: "cleanup",
+            status: evidence.cleanupVerified ? "passed" : "failed",
+            durationMs: Date.now() - started,
+        });
+    }
+    async inventoryCount(args) {
+        try {
+            const result = await this.commands.run(this.config.dockerExecutable, this.dockerArgs(args), {
+                timeoutMs: 30_000,
+                maxOutputBytes: 64 * 1024,
+            });
+            if (result.exitCode !== 0)
+                return -1;
+            return result.stdout.split(/\r?\n/u).filter((line) => line.trim().length > 0).length;
+        }
+        catch {
+            return -1;
+        }
+    }
+}
+export function parseDockerAssignedLoopbackPort(output) {
+    try {
+        const parsed = JSON.parse(output.trim());
+        const bindings = Array.isArray(parsed)
+            ? parsed
+            : typeof parsed === "object" && parsed !== null
+                ? parsed["8080/tcp"]
+                : null;
+        if (!Array.isArray(bindings) || bindings.length !== 1)
+            return null;
+        const binding = bindings[0];
+        if (binding.HostIp !== "127.0.0.1" || typeof binding.HostPort !== "string" || !/^\d{1,5}$/u.test(binding.HostPort)) {
+            return null;
+        }
+        const hostPort = Number(binding.HostPort);
+        return hostPort >= 1 && hostPort <= 65535
+            ? { containerPort: 8080, hostIp: "127.0.0.1", hostPort }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+class SmokeFailure extends Error {
+    code;
+    stage;
+    constructor(code, stage, message) {
+        super(message);
+        this.code = code;
+        this.stage = stage;
+    }
+}
+function failureFrom(error) {
+    if (error instanceof SmokeFailure) {
+        return { code: error.code, stage: error.stage, message: error.message };
+    }
+    if (error instanceof Error && "code" in error && typeof error.code === "string") {
+        return {
+            code: `sandbox_smoke_${String(error.code).toLowerCase()}`,
+            stage: "doctor",
+            message: "The repository sandbox contract or Dockerfile could not be read or validated.",
+        };
+    }
+    return {
+        code: "sandbox_smoke_failed",
+        stage: "unknown",
+        message: "The disposable sandbox smoke attempt failed.",
+    };
+}
+async function writeReport(reportPath, report) {
+    await fs.mkdir(path.dirname(reportPath), { recursive: true, mode: 0o700 });
+    const temporary = `${reportPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(report, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await fs.rename(temporary, reportPath);
+    await fs.chmod(reportPath, 0o600).catch(() => undefined);
+}

package/dist/sandbox/worker-supervisor.d.ts

@@ -0,0 +1,13 @@
+import type { MonotonicLeaseDeadline } from "./lease-watchdog.js";
+export type SandboxTerminationCode = "sandbox_lease_expired" | "sandbox_wall_timeout" | "sandbox_idle_timeout";
+export declare class WorkerDeadlineSupervisor {
+    readonly lease: MonotonicLeaseDeadline;
+    readonly hardWallMs: number;
+    readonly idleMs: number;
+    private readonly startedAtMs;
+    private lastActivityMs;
+    constructor(lease: MonotonicLeaseDeadline, hardWallMs: number, idleMs: number, startedAtMs?: number);
+    touch(nowMs?: number): void;
+    termination(nowMs?: number): SandboxTerminationCode | null;
+}
+export declare function terminationMessage(code: SandboxTerminationCode): string;

package/dist/sandbox/worker-supervisor.js

@@ -0,0 +1,36 @@
+export class WorkerDeadlineSupervisor {
+    lease;
+    hardWallMs;
+    idleMs;
+    startedAtMs;
+    lastActivityMs;
+    constructor(lease, hardWallMs, idleMs, startedAtMs = performance.now()) {
+        this.lease = lease;
+        this.hardWallMs = hardWallMs;
+        this.idleMs = idleMs;
+        this.startedAtMs = startedAtMs;
+        if (!Number.isFinite(hardWallMs) || hardWallMs <= 0 || !Number.isFinite(idleMs) || idleMs <= 0) {
+            throw new Error("Sandbox watchdog limits must be positive.");
+        }
+        this.lastActivityMs = startedAtMs;
+    }
+    touch(nowMs = performance.now()) {
+        this.lastActivityMs = Math.max(this.lastActivityMs, nowMs);
+    }
+    termination(nowMs = performance.now()) {
+        if (this.lease.expired(nowMs))
+            return "sandbox_lease_expired";
+        if (nowMs - this.startedAtMs >= this.hardWallMs)
+            return "sandbox_wall_timeout";
+        if (nowMs - this.lastActivityMs >= this.idleMs)
+            return "sandbox_idle_timeout";
+        return null;
+    }
+}
+export function terminationMessage(code) {
+    switch (code) {
+        case "sandbox_lease_expired": return "The durable execution lease expired inside the sandbox.";
+        case "sandbox_wall_timeout": return "The sandbox reached its hard wall-clock limit.";
+        case "sandbox_idle_timeout": return "The provider produced no process activity before the sandbox idle limit.";
+    }
+}

package/dist/sandbox/worker.d.ts

@@ -0,0 +1 @@
+export {};