@claxedo/sandbox-manager 0.9.0 → 0.10.0

package/dist/drivers/cloudflare.d.ts

@@ -1,4 +1,4 @@
-import { type SandboxDriver, type SandboxDriverEnsureInput, type SandboxListingUnsupported } from "..";
+import { type SandboxDriver, type SandboxDriverEnsureInput, type SandboxListingUnsupported } from "../contract";
 import { type WorkspaceRuntimeControlEnv } from "../runtime-env";
 export type CloudflareSandboxDriverOptions = {
     /** Base URL of the deployed Cloudflare Sandbox Worker (e.g. https://sbx.example.com). */
@@ -20,8 +20,8 @@ export type CloudflareSandboxDriverOptions = {
    *   managementJwksUrl → WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL (config apply)
      */
     controlEnv?: WorkspaceRuntimeControlEnv;
-    /** Default runner injected as WORKSPACE_RUNTIME_RUNNER, for example "opencode". */
-    runner?: string;
+    /** Default native harness injected as WORKSPACE_RUNTIME_NATIVE_HARNESS, for example "opencode". */
+    nativeHarness?: string;
     /** Dynamic runtime env that needs the sandbox id or current lease. */
     env?: (input: SandboxDriverEnsureInput, sandbox: {
         id: string;

package/dist/drivers/cloudflare.mjs

@@ -1,44 +1,41 @@
 // src/constants.ts
 var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
 
-// src/hosted-network-policy.ts
-var SANDBOX_MODEL_PROVIDER_HOSTS = [
-  "api.anthropic.com",
-  "api.openai.com",
-  "generativelanguage.googleapis.com",
-  "openrouter.ai",
-  // Model catalog + engine config, fetched on runner startup.
-  "models.dev",
-  "opencode.ai"
-];
-var SANDBOX_PACKAGE_REGISTRY_HOSTS = [
-  "registry.npmjs.org",
-  "nodejs.org",
-  "pypi.org",
-  "files.pythonhosted.org",
-  "crates.io",
-  "static.crates.io",
-  "index.crates.io",
-  "proxy.golang.org",
-  "sum.golang.org"
-];
-var SANDBOX_BASELINE_EGRESS_HOSTS = [
-  ...SANDBOX_MODEL_PROVIDER_HOSTS,
-  ...SANDBOX_PACKAGE_REGISTRY_HOSTS
-];
-
-// src/index.ts
-function brokeredSecretPlaceholder(name) {
-  return `claxedo-broker:${name}`;
-}
-function brokeredPlaceholderEnv(secrets) {
-  return Object.fromEntries((secrets ?? []).map((secret) => [secret.name, brokeredSecretPlaceholder(secret.name)]));
-}
+// src/driver-billing.ts
+var HOUR_SECONDS = 3600;
+var boatBilling = {
+  source: { url: "https://docs.boat.dev/pricing", readOn: "2026-10-12" },
+  meter: "Boat bills machine time per second while a sandbox runs, at an hourly rate per size; a stopped sandbox costs nothing.",
+  rates: {
+    small: { size: "small", vcpu: 2, memoryGb: 4, usdPerHour: 0.018 },
+    default: { size: "default", vcpu: 4, memoryGb: 8, usdPerHour: 0.036 },
+    large: { size: "large", vcpu: 8, memoryGb: 16, usdPerHour: 0.072 }
+  }
+};
+var CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY = 25e-7;
+var CLOUDFLARE_USD_PER_GB_SECOND_DISK = 7e-8;
+var CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE = 2e-5;
+var CLOUDFLARE_STANDARD_1 = { size: "standard-1", vcpu: 0.5, memoryGb: 4, diskGb: 8 };
+var cloudflareBilling = {
+  source: { url: "https://developers.cloudflare.com/containers/pricing/", readOn: "2026-10-12" },
+  meter: "Cloudflare bills a container for every 10 ms it runs: memory at $0.0000025 per GiB-second and disk at $0.00000007 per GB-second for the whole run, plus CPU at $0.00002 per vCPU-second of active use.",
+  rates: {
+    default: {
+      size: CLOUDFLARE_STANDARD_1.size,
+      vcpu: CLOUDFLARE_STANDARD_1.vcpu,
+      memoryGb: CLOUDFLARE_STANDARD_1.memoryGb,
+      usdPerHour: (CLOUDFLARE_STANDARD_1.memoryGb * CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY + CLOUDFLARE_STANDARD_1.diskGb * CLOUDFLARE_USD_PER_GB_SECOND_DISK) * HOUR_SECONDS
+    }
+  },
+  excludes: `active CPU, billed at $${CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE} per vCPU-second and not measured by Claxedo, and the monthly allowance a Workers Paid plan includes`
+};
 
 // ../sandbox-contract/dist/index.mjs
+var sandboxCheckpointUnusableCauses = ["expired", "runtime_outdated", "runtime_modified", "not_restorable"];
+function isSandboxCheckpointUnusableCause(value) {
+  return sandboxCheckpointUnusableCauses.some((cause) => cause === value);
+}
 var sandboxDriverCredentialFields = {
-  exe: [{ key: "api_token", label: "API Token", secret: true }],
-  daytona: [{ key: "api_key", label: "API Key", secret: true }],
   modal: [
     { key: "token_id", label: "Token ID", secret: true },
     { key: "token_secret", label: "Token Secret", secret: true }
@@ -52,68 +49,38 @@ var sandboxDriverCredentialFields = {
     { key: "api_token", label: "API Token", secret: true },
     { key: "worker_url", label: "Worker URL" }
   ],
-  box: [{ key: "api_key", label: "API Key", secret: true }],
+  boat: [{ key: "api_key", label: "API Key", secret: true }],
   docker: [{ key: "image", label: "Image" }]
 };
 var sandboxDriverLabels = {
-  exe: "exe.dev",
-  daytona: "Daytona",
   modal: "Modal",
   vercel: "Vercel",
   cloudflare: "Cloudflare",
-  box: "Box",
+  boat: "Boat",
   docker: "Docker"
 };
+function cloudflareWorkerBaseUrl(input) {
+  let url;
+  try {
+    url = new URL(input.trim());
+  } catch {
+    throw new Error("Cloudflare Worker URL must be a valid HTTPS endpoint");
+  }
+  if (url.protocol !== "https:" || url.username || url.password || input.includes("?") || input.includes("#")) {
+    throw new Error("Cloudflare Worker URL requires HTTPS without credentials, query or fragment");
+  }
+  return url.origin + url.pathname.replace(/\/+$/, "");
+}
 
 // src/driver-catalog.ts
 var sandboxDriverCatalog = {
-  exe: {
-    id: "exe",
-    label: sandboxDriverLabels.exe,
-    credentialFields: sandboxDriverCredentialFields.exe,
-    metadata: {
-      driverRunsIn: ["worker", "node"],
-      hostStopBehavior: "not-supported",
-      hostResumeBehavior: "same-host",
-      targetAccess: "relay",
-      secretBrokering: "none",
-      egressControl: "none",
-      persistence: {
-        resume: "same-sandbox",
-        capture: "none",
-        clone: true,
-        captureSource: "not-applicable",
-        retention: "provider-managed",
-        restoreMount: "same-resource"
-      }
-    }
-  },
-  daytona: {
-    id: "daytona",
-    label: sandboxDriverLabels.daytona,
-    credentialFields: sandboxDriverCredentialFields.daytona,
-    metadata: {
-      driverRunsIn: ["worker", "node"],
-      hostStopBehavior: "suspends-host",
-      hostResumeBehavior: "same-host",
-      targetAccess: "relay",
-      secretBrokering: "native",
-      // The driver translates names to domainAllowList, or addresses to networkAllowList.
-      egressControl: "hosts-and-cidrs",
-      persistence: {
-        resume: "same-sandbox",
-        capture: "filesystem",
-        clone: false,
-        captureSource: "preserved",
-        retention: "provider-managed",
-        restoreMount: "new-resource"
-      }
-    }
-  },
   modal: {
     id: "modal",
     label: sandboxDriverLabels.modal,
     credentialFields: sandboxDriverCredentialFields.modal,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
@@ -136,6 +103,9 @@ var sandboxDriverCatalog = {
     id: "vercel",
     label: sandboxDriverLabels.vercel,
     credentialFields: sandboxDriverCredentialFields.vercel,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
@@ -158,30 +128,40 @@ var sandboxDriverCatalog = {
     id: "cloudflare",
     label: sandboxDriverLabels.cloudflare,
     credentialFields: sandboxDriverCredentialFields.cloudflare,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
+    billing: cloudflareBilling,
     metadata: {
       driverRunsIn: ["worker"],
-      hostStopBehavior: "not-supported",
+      hostStopBehavior: "terminates-host",
       hostResumeBehavior: "same-host",
+      hostWatchesIdle: true,
       targetAccess: "relay",
       secretBrokering: "native",
       // Credential handlers do not restrict unrelated destinations.
       egressControl: "none",
+      // A container snapshot holds the whole root filesystem; the platform keeps it 30 days past its last restore and offers no deletion.
       persistence: {
         resume: "replacement-restore",
-        capture: "directories",
+        capture: "filesystem",
         clone: false,
         captureSource: "preserved",
         retention: "provider-managed",
-        restoreMount: "copy-on-write"
+        restoreMount: "new-resource"
       }
     }
   },
-  box: {
-    id: "box",
-    label: sandboxDriverLabels.box,
-    credentialFields: sandboxDriverCredentialFields.box,
+  boat: {
+    id: "boat",
+    label: sandboxDriverLabels.boat,
+    credentialFields: sandboxDriverCredentialFields.boat,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
+    billing: boatBilling,
     metadata: {
-      driverRunsIn: ["node"],
+      driverRunsIn: ["worker", "node"],
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
@@ -194,13 +174,17 @@ var sandboxDriverCatalog = {
         captureSource: "not-applicable",
         retention: "provider-managed",
         restoreMount: "same-resource"
-      }
+      },
+      machineClasses: ["small", "default", "large"]
     }
   },
   docker: {
     id: "docker",
     label: sandboxDriverLabels.docker,
     credentialFields: sandboxDriverCredentialFields.docker,
+    runtimeNetwork: { controlPlane: "docker-host", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["local"],
       hostStopBehavior: "terminates-host",
@@ -220,6 +204,37 @@ var sandboxDriverCatalog = {
   }
 };
 
+// src/egress-policy.ts
+function brokeredSecretPlaceholder(name) {
+  return `claxedo-broker:${name}`;
+}
+function brokeredPlaceholderEnv(secrets) {
+  return Object.fromEntries((secrets ?? []).map((secret) => [secret.name, brokeredSecretPlaceholder(secret.name)]));
+}
+
+// src/lease-failure.ts
+var SandboxRuntimeBootError = class extends Error {
+  runtimeBootFailed = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxRuntimeBootError";
+  }
+};
+var SandboxCheckpointUnusableError = class extends Error {
+  constructor(checkpointUnusable, reason) {
+    super(reason);
+    this.checkpointUnusable = checkpointUnusable;
+    this.name = "SandboxCheckpointUnusableError";
+  }
+};
+var SandboxProviderKeyRefusedError = class extends Error {
+  providerKeyRefused = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxProviderKeyRefusedError";
+  }
+};
+
 // ../claxedo-helpers/dist/guards.mjs
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -234,13 +249,43 @@ function text(input) {
 }
 
 // src/runtime-env.ts
+var WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS = [
+  "WORKSPACE_RUNTIME_WORKSPACE_ID",
+  "WORKSPACE_RUNTIME_HOST_ID",
+  "WORKSPACE_RUNTIME_RELAY_WORKSPACE_IDS"
+];
+function workspaceRuntimeIdentityEnvConflicts(env) {
+  if (!env) return [];
+  return WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS.filter((key) => env[key] !== void 0);
+}
+function assertWorkspaceRuntimeIdentityEnv(env) {
+  const conflicts = workspaceRuntimeIdentityEnvConflicts(env);
+  if (conflicts.length === 0) return;
+  throw new Error(
+    `sandbox env cannot set runtime identity ${conflicts.join(", ")}: the driver's placement owns the identity its target reports and the lease records`
+  );
+}
+var WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS = /* @__PURE__ */ new Set([
+  ...WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS,
+  "WORKSPACE_RUNTIME_DIRECTORY",
+  "WORKSPACE_RUNTIME_PORT",
+  "WORKSPACE_RUNTIME_HOST",
+  "WORKSPACE_RUNTIME_SOURCE_KIND",
+  "WORKSPACE_RUNTIME_GIT_REPO_URL",
+  "WORKSPACE_RUNTIME_GIT_BRANCH",
+  "WORKSPACE_RUNTIME_NATIVE_HARNESS",
+  "WORKSPACE_RUNTIME_RELAY_JWKS_URL",
+  "WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL",
+  "WORKSPACE_RUNTIME_SESSION_AUTHORITY_URL"
+]);
 function workspaceRuntimeBootEnv(input) {
+  assertWorkspaceRuntimeIdentityEnv(input.env);
   const env = {
     ...workspaceRuntimeTargetEnv(input),
     ...workspaceRuntimeSourceEnv(input),
     ...input.env
   };
-  if (input.runner) env.WORKSPACE_RUNTIME_RUNNER = input.runner;
+  if (input.nativeHarness) env.WORKSPACE_RUNTIME_NATIVE_HARNESS = input.nativeHarness;
   if (input.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = input.controlEnv.relayJwksUrl;
   if (input.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = input.controlEnv.relayVerifyPem;
   if (input.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = input.controlEnv.managementJwksUrl;
@@ -265,21 +310,29 @@ function workspaceRuntimeSourceEnv(input) {
   };
 }
 
+// src/runtime-version.ts
+var MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+
 // src/drivers/cloudflare.ts
 function registryEntries(input) {
-  if (!Array.isArray(input)) return [];
-  return input.flatMap((item) => {
+  if (!Array.isArray(input)) throw new Error("Invalid Cloudflare sandbox listing: expected sandboxes array");
+  return input.map((item) => {
     const row = asRecord(item);
-    if (!row) return [];
-    const entries = Object.entries(row).filter((entry) => typeof entry[1] === "string");
-    return [Object.fromEntries(entries)];
+    if (!row || typeof row.sandboxId !== "string" || !row.sandboxId) {
+      throw new Error("Invalid Cloudflare sandbox listing entry: expected sandboxId");
+    }
+    const entries = Object.entries(row).map(([key, value]) => {
+      if (typeof value !== "string") throw new Error(`Invalid Cloudflare sandbox listing label: ${key}`);
+      return [key, value];
+    });
+    return Object.fromEntries(entries);
   });
 }
 var DEFAULT_WORKSPACE_DIR = "/workspace";
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
 var DEFAULT_TIMEOUT_MS = 45e3;
 var DEFAULT_ENSURE_TIMEOUT_MS = 3e5;
-var WORKSPACE_DIRECTORY_LABEL = "claxedo.workspaceDirectory";
+var DEFAULT_SNAPSHOT_TIMEOUT_MS = 18e4;
 function deadlineSignal(timeoutMs) {
   const controller = new AbortController();
   const timer = setTimeout(
@@ -293,13 +346,7 @@ function deadlineSignal(timeoutMs) {
     }
   };
 }
-var RUNTIME_DATA_DIR = "/var/lib/claxedo";
-function captureDirectories(workspaceDirectory) {
-  return [workspaceDirectory, RUNTIME_DATA_DIR];
-}
-function cleanUrl(input) {
-  return input.replace(/\/+$/, "");
-}
+var RUNTIME_HOME = "/home/claxedo";
 function sandboxIdFor(workspaceId) {
   return `claxedo-${workspaceId}`;
 }
@@ -311,20 +358,26 @@ var CloudflareSandboxListingUnsupportedError = class extends Error {
   }
 };
 function createCloudflareSandboxDriver(options) {
-  const doFetch = options.fetch ?? fetch;
+  const fetchWorker = options.fetch ?? fetch;
+  const doFetch = async (url, init) => {
+    const response = await fetchWorker(url, { ...init, redirect: "manual" });
+    if (response.redirected || response.status >= 300 && response.status < 400) throw new Error("Cloudflare Worker redirects are not allowed");
+    return response;
+  };
   const runtimePort = options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
   const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
   const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const ensureTimeoutMs = options.timeoutMs ?? DEFAULT_ENSURE_TIMEOUT_MS;
-  const base = cleanUrl(options.workerUrl);
+  const snapshotTimeoutMs = options.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS;
+  const base = cloudflareWorkerBaseUrl(options.workerUrl);
   const headers = {
     Authorization: `Bearer ${options.apiToken}`,
     "Content-Type": "application/json"
   };
   async function call(sandboxId, action, body, method = "POST") {
     const url = `${base}/sandbox/${encodeURIComponent(sandboxId)}${action ? `/${action}` : ""}`;
-    const deadline = deadlineSignal(action === "ensure-runtime" ? ensureTimeoutMs : timeoutMs);
+    const deadline = deadlineSignal(action === "ensure-runtime" ? ensureTimeoutMs : action === "snapshot" ? snapshotTimeoutMs : timeoutMs);
     try {
       const res = await doFetch(url, {
         method,
@@ -350,15 +403,15 @@ function createCloudflareSandboxDriver(options) {
       host: "0.0.0.0",
       source: input.source,
       env: {
-        // Must match the checkpoint capture set below.
-        CLAXEDO_DATA_DIR: RUNTIME_DATA_DIR,
+        HOME: RUNTIME_HOME,
+        CLAXEDO_DATA_DIR: `${RUNTIME_HOME}/.claxedo`,
         ...input.env,
         ...await options.env?.(input, { id: hostId }),
         // Last, so no caller-supplied variable of the same name can stand in
         // for a placeholder the outbound handler matches on.
         ...brokeredPlaceholderEnv(input.secrets)
       },
-      runner: options.runner,
+      nativeHarness: options.nativeHarness,
       controlEnv: options.controlEnv
     });
   }
@@ -399,21 +452,26 @@ function createCloudflareSandboxDriver(options) {
         // what makes this driver's `list()` (and therefore GC) possible at all.
         // Not container env — labels are control-plane metadata.
         labels: input.labels,
-        ...input.bootSource?.kind === "driver-snapshot" ? { restore: { backupId: input.bootSource.snapshotId, directories: captureDirectories(workspaceDirectory(input)) } } : {},
+        ...input.bootSource?.kind === "driver-snapshot" ? { restore: { snapshotId: input.bootSource.snapshotId }, minimumRuntimeVersion: MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION } : {},
         ...egress ? { egress } : {}
       }
     ).catch((error) => {
       if (error instanceof Error && error.name === "TimeoutError") return void 0;
       throw error;
     });
-    if (!response) return { provisioning: true, retryAfterMs: 2e3 };
+    if (!response) return { provisioning: true, retryAfterMs: 0 };
     const { status, data } = response;
     const runtimeUrl = text(data.url);
     if (status === 503 && data.error === "workspace-runtime did not become ready") {
-      return { provisioning: true, retryAfterMs: 2e3 };
+      return { provisioning: true, retryAfterMs: 0 };
+    }
+    if (data.exited === true) throw new SandboxRuntimeBootError(text(data.error) ?? "The workspace runtime exited before it was ready");
+    if (status === 410 && isSandboxCheckpointUnusableCause(data.checkpointUnusable)) {
+      throw new SandboxCheckpointUnusableError(data.checkpointUnusable, text(data.error) ?? "This workspace's saved files cannot be restored; choose Start fresh.");
     }
     if (status >= 400 || !runtimeUrl) {
-      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${text(data.error) ?? "no runtime url"}`);
+      const reason = `Cloudflare ensure-runtime failed (${status}): ${text(data.error) ?? "no runtime url"}`;
+      throw status === 401 || status === 403 ? new SandboxProviderKeyRefusedError(reason) : new Error(reason);
     }
     const targetOut = {
       workspaceId: input.workspaceId,
@@ -425,10 +483,7 @@ function createCloudflareSandboxDriver(options) {
         id: "cloudflare",
         resourceId: sandboxId
       },
-      labels: {
-        ...input.labels,
-        [WORKSPACE_DIRECTORY_LABEL]: workspaceDirectory(input)
-      }
+      labels: input.labels
     };
     return targetOut;
   }
@@ -437,12 +492,10 @@ function createCloudflareSandboxDriver(options) {
     // Provider-state enumeration, served by the sandbox Worker's registry
     // (`GET /sandboxes`) rather than by Cloudflare's own APIs.
     //
-    // Why a registry is REQUIRED here, checked against the installed SDK
-    // (@cloudflare/sandbox 0.8.9) rather than assumed:
+    // Why a registry is REQUIRED here:
     //
-    //  1. The SDK has no enumeration surface. `getSandbox(ns, id)` is
-    //     get-or-create against a Durable Object; nothing in its exports lists
-    //     a namespace. `listDurableObjectIds` is `cloudflare:test`-only.
+    //  1. A Durable Object namespace has no enumeration surface: `getByName`
+    //     is get-or-create, and `listDurableObjectIds` is `cloudflare:test`-only.
     //  2. The account-level REST list-objects endpoint returns
     //     `{ id: <hex>, hasStoredData }` and nothing else. `idFromName` is
     //     one-way, so a hex id cannot be mapped back to `claxedo-<workspaceId>`
@@ -455,12 +508,7 @@ function createCloudflareSandboxDriver(options) {
     // So the Worker records each sandbox on `ensure-runtime` and drops it on
     // destroy — the pattern Cloudflare recommends for precisely this reason.
     //
-    // A Worker predating that route (or deployed with no R2 binding) answers
-    // 404/501, which THROWS `CloudflareSandboxListingUnsupportedError` rather
-    // than returning `[]`. An empty list from an old Worker would mean "nothing
-    // is orphaned" and hand GC a silent success — the defect this whole
-    // workstream removes. The manager turns that throw back into
-    // `listingUnsupported`, so an un-upgraded Worker is loudly visible.
+    // A missing registry route or R2 binding cannot establish an empty inventory.
     async list() {
       const deadline = deadlineSignal(timeoutMs);
       try {
@@ -469,10 +517,14 @@ function createCloudflareSandboxDriver(options) {
           headers,
           signal: deadline.signal
         });
-        const data = asRecord(await res.json().catch(() => ({}))) ?? {};
-        if (res.status === 404 || res.status === 501 || data.supported === false) {
+        if (res.status === 404 || res.status === 501) {
+          throw new CloudflareSandboxListingUnsupportedError(`Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}); requires the /sandboxes registry route and SANDBOX_REGISTRY binding`);
+        }
+        const data = asRecord(await res.json());
+        if (!data) throw new Error("Invalid Cloudflare sandbox listing envelope");
+        if (data.supported === false) {
           throw new CloudflareSandboxListingUnsupportedError(
-            text(data.error) ?? `Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}) \u2014 deploy a Worker with the /sandboxes registry route and an R2 BACKUP_BUCKET binding`
+            text(data.error) ?? `Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}) \u2014 deploy a Worker with the /sandboxes registry route and an R2 SANDBOX_REGISTRY binding`
           );
         }
         if (!res.ok) {
@@ -480,7 +532,6 @@ function createCloudflareSandboxDriver(options) {
         }
         return registryEntries(data.sandboxes).flatMap((entry) => {
           const sandboxId = entry.sandboxId;
-          if (!sandboxId) return [];
           const { sandboxId: _id, ...labels } = entry;
           const target = {
             ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
@@ -502,8 +553,9 @@ function createCloudflareSandboxDriver(options) {
     },
     metadata: {
       driverRunsIn: ["worker"],
-      hostStopBehavior: "not-supported",
+      hostStopBehavior: "terminates-host",
       hostResumeBehavior: "same-host",
+      hostWatchesIdle: true,
       targetAccess: "relay",
       secretBrokering: "native",
       egressControl: "none",
@@ -511,10 +563,24 @@ function createCloudflareSandboxDriver(options) {
     },
     ensureHost,
     async touch(target) {
-      await call(target.sandboxId, "touch-runtime", { port: runtimePort }).catch(() => void 0);
+      const { status, data } = await call(target.sandboxId, "touch-runtime", { port: runtimePort });
+      if (status < 200 || status >= 300 || data.ok !== true) {
+        throw new Error(`Cloudflare touch failed (${status}) for ${target.sandboxId}`);
+      }
     },
     async stop(target) {
-      void target;
+      const { status, data } = await call(target.sandboxId, "stop", { epoch: target.epoch });
+      if (status >= 400 || data.ok !== true) {
+        throw new Error(`Cloudflare stop failed (${status}) for ${target.sandboxId}: ${text(data.error) ?? "not stopped"}`);
+      }
+    },
+    // The sandbox's object outlives its container and keeps the snapshots it took, so a container that is not running is a stopped host, never a gone one.
+    async inspect(target) {
+      const { status, data } = await call(target.sandboxId, "inspect", {});
+      if (status < 200 || status >= 300 || typeof data.running !== "boolean") {
+        throw new Error(`Cloudflare inspect failed (${status}) for ${target.sandboxId}: ${text(data.error) ?? "no container state"}`);
+      }
+      return data.running ? "serving" : "stopped";
     },
     async destroy(target) {
       const { status } = await call(target.sandboxId, "", {}, "DELETE");
@@ -523,17 +589,12 @@ function createCloudflareSandboxDriver(options) {
       }
     },
     async snapshot(target) {
-      const directory = target.labels?.[WORKSPACE_DIRECTORY_LABEL] ?? workspaceDir;
-      const { status, data } = await call(
-        target.sandboxId,
-        "backup",
-        { directories: captureDirectories(directory) }
-      );
-      const backupId = text(data.backupId);
-      if (status >= 400 || !backupId) {
-        throw new Error(`Cloudflare backup failed (${status}): ${text(data.error) ?? "no backup id"}`);
+      const { status, data } = await call(target.sandboxId, "snapshot", {});
+      const snapshotId = text(data.snapshotId);
+      if (status >= 400 || !snapshotId) {
+        throw new Error(`Cloudflare snapshot failed (${status}): ${text(data.error) ?? "no snapshot id"}`);
       }
-      return { snapshotId: backupId };
+      return { snapshotId };
     }
   };
 }

package/dist/drivers/docker.d.ts

@@ -1,17 +1,18 @@
-import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+import type { SandboxDriver, SandboxDriverEnsureInput } from "../contract";
 type SandboxEnv = Record<string, string | undefined>;
 export type DockerCommandResult = {
     stdout?: string | Buffer;
     stderr?: string | Buffer;
 };
-export type DockerCommandRunner = (args: string[], timeoutMs?: number) => Promise<DockerCommandResult>;
+/** `env` joins the docker CLI's own environment; a `--env NAME` argument with no value reads NAME from it. */
+export type DockerCommandRunner = (args: string[], timeoutMs?: number, env?: Record<string, string>) => Promise<DockerCommandResult>;
 export type DockerHealthFetch = (input: string, init?: RequestInit) => Promise<Response>;
 export type DockerSandboxDriverOptions = {
     image: string;
     runtimePort?: number;
     runtimeCommand?: string;
     workspaceDir?: string;
-    runner?: string;
+    nativeHarness?: string;
     env?: (input: SandboxDriverEnsureInput, host: {
         id: string;
     }) => Record<string, string> | Promise<Record<string, string>>;