@claxedo/sandbox-manager 0.7.0 → 0.10.0

package/dist/drivers/cloudflare.mjs

@@ -1,95 +1,93 @@
 // 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/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 = {
+  modal: [
+    { key: "token_id", label: "Token ID", secret: true },
+    { key: "token_secret", label: "Token Secret", secret: true }
+  ],
+  vercel: [
+    { key: "access_token", label: "Access Token", secret: true },
+    { key: "team_id", label: "Team ID" },
+    { key: "project_id", label: "Project ID" }
+  ],
+  cloudflare: [
+    { key: "api_token", label: "API Token", secret: true },
+    { key: "worker_url", label: "Worker URL" }
+  ],
+  boat: [{ key: "api_key", label: "API Key", secret: true }],
+  docker: [{ key: "image", label: "Image" }]
+};
+var sandboxDriverLabels = {
+  modal: "Modal",
+  vercel: "Vercel",
+  cloudflare: "Cloudflare",
+  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: "exe.dev",
-    credentialFields: [{ key: "api_token", label: "API Token", secret: true }],
-    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: "Daytona",
-    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
-    metadata: {
-      driverRunsIn: ["worker", "node"],
-      hostStopBehavior: "suspends-host",
-      hostResumeBehavior: "same-host",
-      targetAccess: "relay",
-      secretBrokering: "native",
-      // Daytona is the only driver that can filter egress by NAME as well as
-      // by address: `domainAllowList` (names) alongside `networkAllowList`
-      // (CIDRs), with `networkBlockAll` as the deny-all floor.
-      egressControl: "hosts-and-cidrs",
-      persistence: {
-        resume: "same-sandbox",
-        capture: "filesystem",
-        clone: false,
-        captureSource: "preserved",
-        retention: "provider-managed",
-        restoreMount: "new-resource"
-      }
-    }
-  },
   modal: {
     id: "modal",
-    label: "Modal",
-    credentialFields: [
-      { key: "token_id", label: "Token ID", secret: true },
-      { key: "token_secret", label: "Token Secret", secret: true }
-    ],
+    label: sandboxDriverLabels.modal,
+    credentialFields: sandboxDriverCredentialFields.modal,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
       hostResumeBehavior: "replacement-host",
       targetAccess: "relay",
       secretBrokering: "none",
-      // Modal can cut the network entirely (`blockNetwork`) but cannot express
-      // an allowlist, and its driver throws on a host policy. A blackout is
-      // not containment for a workspace that has to clone and reach a model.
+      // The driver does not install Modal's domain allowlist or alpha sidecar.
       egressControl: "none",
       persistence: {
         resume: "replacement-restore",
@@ -103,20 +101,18 @@ var sandboxDriverCatalog = {
   },
   vercel: {
     id: "vercel",
-    label: "Vercel",
-    credentialFields: [
-      { key: "access_token", label: "Access Token", secret: true },
-      { key: "team_id", label: "Team ID" },
-      { key: "project_id", label: "Project ID" }
-    ],
+    label: sandboxDriverLabels.vercel,
+    credentialFields: sandboxDriverCredentialFields.vercel,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
       hostResumeBehavior: "replacement-host",
       targetAccess: "relay",
       secretBrokering: "native",
-      // Vercel's sandbox firewall takes a hostname allow list (or "deny-all"),
-      // never CIDRs.
+      // The driver translates hosts only; the SDK's subnet rules are not wired to net.cidrs.
       egressControl: "hosts",
       persistence: {
         resume: "replacement-restore",
@@ -130,40 +126,42 @@ var sandboxDriverCatalog = {
   },
   cloudflare: {
     id: "cloudflare",
-    label: "Cloudflare",
-    credentialFields: [
-      { key: "api_token", label: "API Token", secret: true },
-      { key: "worker_url", label: "Worker URL" }
-    ],
+    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: "proxy",
-      // The Cloudflare Sandbox Worker exposes no egress filter: its broker
-      // (drivers/cloudflare-egress.ts) is an OPT-IN proxy the sandbox chooses
-      // to route brokered-credential requests through, not a boundary. The
-      // driver therefore drops `net` entirely — which is exactly why this
-      // must be declared, so the manager refuses instead of provisioning a
-      // sandbox the caller believes is contained.
+      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: "Box",
-    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+  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",
@@ -176,13 +174,17 @@ var sandboxDriverCatalog = {
         captureSource: "not-applicable",
         retention: "provider-managed",
         restoreMount: "same-resource"
-      }
+      },
+      machineClasses: ["small", "default", "large"]
     }
   },
   docker: {
     id: "docker",
-    label: "Docker",
-    credentialFields: [{ key: "image", label: "Image" }],
+    label: sandboxDriverLabels.docker,
+    credentialFields: sandboxDriverCredentialFields.docker,
+    runtimeNetwork: { controlPlane: "docker-host", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["local"],
       hostStopBehavior: "terminates-host",
@@ -202,7 +204,94 @@ 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);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+
+// src/json.ts
+function text(input) {
+  return typeof input === "string" && input.length > 0 ? input : void 0;
+}
+
 // 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.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;
+  if (input.controlEnv?.sessionAuthorityUrl) env.WORKSPACE_RUNTIME_SESSION_AUTHORITY_URL = input.controlEnv.sessionAuthorityUrl;
+  return env;
+}
 function workspaceRuntimeTargetEnv(input) {
   return {
     WORKSPACE_RUNTIME_WORKSPACE_ID: input.workspaceId,
@@ -221,18 +310,43 @@ 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)) throw new Error("Invalid Cloudflare sandbox listing: expected sandboxes array");
+  return input.map((item) => {
+    const row = asRecord(item);
+    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 WORKSPACE_DIRECTORY_LABEL = "claxedo.workspaceDirectory";
-var RUNTIME_DATA_DIR = "/var/lib/claxedo";
-function captureDirectories(workspaceDirectory) {
-  return [workspaceDirectory, RUNTIME_DATA_DIR];
-}
-function cleanUrl(input) {
-  return input.replace(/\/+$/, "");
+var DEFAULT_ENSURE_TIMEOUT_MS = 3e5;
+var DEFAULT_SNAPSHOT_TIMEOUT_MS = 18e4;
+function deadlineSignal(timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new DOMException("The operation timed out", "TimeoutError")),
+    timeoutMs
+  );
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timer);
+    }
+  };
 }
+var RUNTIME_HOME = "/home/claxedo";
 function sandboxIdFor(workspaceId) {
   return `claxedo-${workspaceId}`;
 }
@@ -244,63 +358,83 @@ 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 base = cleanUrl(options.workerUrl);
+  const ensureTimeoutMs = options.timeoutMs ?? DEFAULT_ENSURE_TIMEOUT_MS;
+  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 res = await doFetch(url, {
-      method,
-      headers,
-      ...method === "POST" ? { body: JSON.stringify(body) } : {},
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    const data = await res.json().catch(() => ({}));
-    return { status: res.status, data };
+    const deadline = deadlineSignal(action === "ensure-runtime" ? ensureTimeoutMs : action === "snapshot" ? snapshotTimeoutMs : timeoutMs);
+    try {
+      const res = await doFetch(url, {
+        method,
+        headers,
+        ...method === "POST" ? { body: JSON.stringify(body) } : {},
+        signal: deadline.signal
+      });
+      const data = asRecord(await res.json().catch(() => ({}))) ?? {};
+      return { status: res.status, data };
+    } finally {
+      deadline.cleanup();
+    }
   }
   function workspaceDirectory(input) {
     return input.workspaceRoot ?? workspaceDir;
   }
   async function bootEnv(input, hostId) {
-    const env = {
-      ...workspaceRuntimeTargetEnv({
-        workspaceId: input.workspaceId,
-        hostId,
-        directory: workspaceDirectory(input),
-        port: runtimePort,
-        host: "0.0.0.0"
-      }),
-      ...workspaceRuntimeSourceEnv({ source: input.source }),
-      // Must match RUNTIME_DATA_DIR's capture set below — see its comment.
-      CLAXEDO_DATA_DIR: RUNTIME_DATA_DIR,
-      ...input.env,
-      ...await options.env?.(input, { id: hostId })
-    };
-    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
-    if (options.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = options.controlEnv.relayJwksUrl;
-    if (options.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = options.controlEnv.relayVerifyPem;
-    if (options.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = options.controlEnv.managementJwksUrl;
-    return env;
+    return workspaceRuntimeBootEnv({
+      workspaceId: input.workspaceId,
+      hostId,
+      directory: workspaceDirectory(input),
+      port: runtimePort,
+      host: "0.0.0.0",
+      source: input.source,
+      env: {
+        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)
+      },
+      nativeHarness: options.nativeHarness,
+      controlEnv: options.controlEnv
+    });
   }
   function egressRegistrations(input) {
-    if (!input.secrets?.length) return void 0;
+    if (input.secrets === void 0) return void 0;
     return input.secrets.map((secret) => {
       if (!secret.header) {
         throw new Error(
-          `cloudflare brokered secret "${secret.name}" requires a header \u2014 the egress proxy injects the value as an HTTP header`
+          `cloudflare brokered secret "${secret.name}" requires a header for native outbound injection`
         );
       }
       if (secret.hosts.length === 0) {
         throw new Error(`cloudflare brokered secret "${secret.name}" requires at least one host in its egress allowlist`);
       }
-      return { hosts: secret.hosts, header: secret.header, value: secret.value };
+      const value = secret.scheme ? `${secret.scheme} ${secret.value}` : secret.value;
+      return {
+        name: secret.name,
+        hosts: secret.hosts,
+        header: secret.header,
+        value,
+        methods: [...secret.methods ?? []],
+        pathPrefixes: [...secret.pathPrefixes ?? []]
+      };
     });
   }
   async function ensureHost(input) {
@@ -318,33 +452,38 @@ 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;
-    if (status >= 500) return { provisioning: true, retryAfterMs: 2e3 };
-    if (status >= 400 || !data?.url) {
-      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${data?.error ?? "no runtime url"}`);
+    const runtimeUrl = text(data.url);
+    if (status === 503 && data.error === "workspace-runtime did not become ready") {
+      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) {
+      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,
       sandboxId,
-      url: data.url,
+      url: runtimeUrl,
       hostId,
       driverResourceId: sandboxId,
       driver: {
         id: "cloudflare",
         resourceId: sandboxId
       },
-      labels: {
-        ...input.labels,
-        [WORKSPACE_DIRECTORY_LABEL]: workspaceDirectory(input)
-      }
+      labels: input.labels
     };
     return targetOut;
   }
@@ -353,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>`
@@ -371,61 +508,79 @@ 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 res = await doFetch(`${base}/sandboxes`, {
-        method: "GET",
-        headers,
-        signal: AbortSignal.timeout(timeoutMs)
-      });
-      const data = await res.json().catch(() => ({}));
-      if (res.status === 404 || res.status === 501 || data?.supported === false) {
-        throw new CloudflareSandboxListingUnsupportedError(
-          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`
-        );
-      }
-      if (!res.ok) {
-        throw new Error(`Cloudflare sandbox listing failed (${res.status}): ${data?.error ?? "unknown error"}`);
+      const deadline = deadlineSignal(timeoutMs);
+      try {
+        const res = await doFetch(`${base}/sandboxes`, {
+          method: "GET",
+          headers,
+          signal: deadline.signal
+        });
+        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 SANDBOX_REGISTRY binding`
+          );
+        }
+        if (!res.ok) {
+          throw new Error(`Cloudflare sandbox listing failed (${res.status}): ${text(data.error) ?? "unknown error"}`);
+        }
+        return registryEntries(data.sandboxes).flatMap((entry) => {
+          const sandboxId = entry.sandboxId;
+          const { sandboxId: _id, ...labels } = entry;
+          const target = {
+            ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
+            sandboxId,
+            // Identity, not a reachable address — GC only names what it destroys.
+            url: `${base}/sandbox/${encodeURIComponent(sandboxId)}/proxy`,
+            // Matches `ensureHost`'s `hostId = sandboxId`, so a live sandbox
+            // cannot fail GC's identity check and be destroyed as an orphan.
+            hostId: sandboxId,
+            driverResourceId: sandboxId,
+            labels,
+            driver: { id: "cloudflare", resourceId: sandboxId }
+          };
+          return [target];
+        });
+      } finally {
+        deadline.cleanup();
       }
-      return (data.sandboxes ?? []).flatMap((entry) => {
-        const sandboxId = entry.sandboxId;
-        if (!sandboxId) return [];
-        const { sandboxId: _id, ...labels } = entry;
-        const target = {
-          ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
-          sandboxId,
-          // Identity, not a reachable address — GC only names what it destroys.
-          url: `${base}/sandbox/${encodeURIComponent(sandboxId)}/proxy`,
-          // Matches `ensureHost`'s `hostId = sandboxId`, so a live sandbox
-          // cannot fail GC's identity check and be destroyed as an orphan.
-          hostId: sandboxId,
-          driverResourceId: sandboxId,
-          labels,
-          driver: { id: "cloudflare", resourceId: sandboxId }
-        };
-        return [target];
-      });
     },
     metadata: {
       driverRunsIn: ["worker"],
-      hostStopBehavior: "not-supported",
+      hostStopBehavior: "terminates-host",
       hostResumeBehavior: "same-host",
+      hostWatchesIdle: true,
       targetAccess: "relay",
-      secretBrokering: "proxy",
+      secretBrokering: "native",
       egressControl: "none",
       persistence: sandboxDriverCatalog.cloudflare.metadata.persistence
     },
     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");
@@ -434,16 +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) }
-      );
-      if (status >= 400 || !data.backupId) {
-        throw new Error(`Cloudflare backup failed (${status}): ${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: data.backupId };
+      return { snapshotId };
     }
   };
 }