@claxedo/sandbox-manager 0.10.1 → 0.10.3

package/dist/index.mjs

@@ -83,9 +83,9 @@ function sandboxNetworkPolicyWithBrokeredHosts(policy, secrets) {
     ...hosts.length ? { hosts } : {}
   };
 }
-function sandboxEgressDisposition(control, net) {
+function sandboxEgressDisposition(control, net, uncontained = "refuse") {
   if (!net || net.mode === "allow-all") return { action: "enforce" };
-  if (control === "none") return { action: "withhold", reason: "sandbox_egress_uncontained" };
+  if (control === "none") return { action: uncontained === "allow" ? "withhold" : "refuse", reason: "sandbox_egress_uncontained" };
   const hosts = net.hosts?.length ?? 0;
   const cidrs = net.cidrs?.length ?? 0;
   if (hosts === 0 && cidrs === 0) return { action: "enforce" };
@@ -110,6 +110,27 @@ var boatBilling = {
     large: { size: "large", vcpu: 8, memoryGb: 16, usdPerHour: 0.072 }
   }
 };
+var AGENT37_USD_PER_MONTH = { vcpu: 0.8, memoryGb: 0.7, diskGb: 0.09 };
+var AGENT37_MONTH_HOURS = 730;
+var agent37MachineShapes = {
+  small: { cpu: 2, memory: 4, disk: 10 },
+  default: { cpu: 4, memory: 8, disk: 20 },
+  large: { cpu: 4, memory: 16, disk: 40 }
+};
+function agent37Rate(shape) {
+  const usdPerMonth = shape.cpu * AGENT37_USD_PER_MONTH.vcpu + shape.memory * AGENT37_USD_PER_MONTH.memoryGb + shape.disk * AGENT37_USD_PER_MONTH.diskGb;
+  return { size: `${shape.cpu} vCPU / ${shape.memory} GB`, vcpu: shape.cpu, memoryGb: shape.memory, usdPerHour: usdPerMonth / AGENT37_MONTH_HOURS };
+}
+var agent37Billing = {
+  source: { url: "https://www.agent37.com/docs/agents-api/billing", readOn: "2026-11-11" },
+  meter: "Agent37 meters an instance per minute at a monthly rate over 730 hours: $0.80 per vCPU, $0.70 per GB of memory and $0.09 per GB of disk while it runs, and the disk alone while it is stopped.",
+  rates: {
+    small: agent37Rate(agent37MachineShapes.small),
+    default: agent37Rate(agent37MachineShapes.default),
+    large: agent37Rate(agent37MachineShapes.large)
+  },
+  excludes: `the disk of a stopped instance, billed at $${AGENT37_USD_PER_MONTH.diskGb} per GB a month until the instance is deleted`
+};
 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;
@@ -314,16 +335,17 @@ function isPrivateIpAddress(ip) {
     return isPrivateIpv4(embedded);
   return false;
 }
-var sandboxCheckpointUnusableCauses = ["expired", "runtime_outdated", "runtime_modified", "not_restorable"];
+var sandboxCheckpointUnusableCauses = ["expired", "runtime_modified", "not_restorable"];
 function isSandboxCheckpointUnusableCause(value) {
   return sandboxCheckpointUnusableCauses.some((cause) => cause === value);
 }
-var sandboxDriverIds = ["modal", "vercel", "cloudflare", "boat", "docker"];
+var sandboxDriverIds = ["modal", "vercel", "cloudflare", "boat", "agent37", "docker"];
 var sandboxDriverLabels = {
   modal: "Modal",
   vercel: "Vercel",
   cloudflare: "Cloudflare",
   boat: "Boat",
+  agent37: "Agent37",
   docker: "Docker"
 };
 function isSandboxDriverID(input) {
@@ -378,6 +400,17 @@ var SandboxRuntimeBootError = class extends Error {
     this.name = "SandboxRuntimeBootError";
   }
 };
+function isSandboxImageDownloadFailure(err) {
+  return err instanceof Error && "imageDownloadFailed" in err && err.imageDownloadFailed === true;
+}
+var SandboxImageDownloadError = class extends Error {
+  imageDownloadFailed = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxImageDownloadError";
+  }
+};
+var SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED = "update_download_interrupted";
 function isSandboxCheckpointUnusable(err) {
   return !!err && typeof err === "object" && isSandboxCheckpointUnusableCause(err.checkpointUnusable);
 }
@@ -423,6 +456,13 @@ function sandboxDriverLabel(driver) {
 }
 var PROVIDER_KEY_REFUSED = "provider_key_refused:";
 var PROVIDER_FAILED = "provider_failed:";
+var EGRESS_UNCONTAINED = "sandbox_egress_uncontained:";
+function sandboxEgressUncontainedError(driver) {
+  return `${EGRESS_UNCONTAINED}${driver}`;
+}
+function uncontainedEgressReason(provider) {
+  return `${provider} cannot contain a sandbox's network; an org admin can allow unrestricted internet for ${provider} machines in Settings \u2192 Sandbox providers.`;
+}
 function sandboxProviderKeyRefusedError(driver, message) {
   return `${PROVIDER_KEY_REFUSED}${driver}: ${message}`;
 }
@@ -516,7 +556,8 @@ var SANDBOX_RUNTIME_UNHEALTHY = "runtime_unhealthy";
 var SANDBOX_RETRY_CAP_EXCEEDED = "runtime_retry_cap_exceeded";
 var CODED_REASONS = /* @__PURE__ */ new Map([
   [SANDBOX_RUNTIME_UNHEALTHY, "The workspace machine stopped answering."],
-  [SANDBOX_RETRY_CAP_EXCEEDED, "Several tries in a row failed; try again later."]
+  [SANDBOX_RETRY_CAP_EXCEEDED, "Several tries in a row failed; try again later."],
+  [SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED, "The update couldn't finish downloading; your workspace is still running. Try again."]
 ]);
 function firstLine(text) {
   return text.split("\n", 1)[0]?.trim() ?? text;
@@ -530,6 +571,8 @@ function sandboxStartFailureReason(error) {
   if (keyRefused !== void 0) return `${sandboxDriverLabel(keyRefused)} refused the sandbox provider key; fix it in Settings \u2192 Sandbox providers.`;
   const failed = codedDriver(error, PROVIDER_FAILED);
   if (failed !== void 0) return `${sandboxDriverLabel(failed)} returned an error.`;
+  const uncontained = codedDriver(error, EGRESS_UNCONTAINED);
+  if (uncontained !== void 0) return uncontainedEgressReason(sandboxDriverLabel(uncontained));
   return CODED_REASONS.get(error) ?? firstLine(error);
 }
 var LEASE_ENDED_ERRORS = /* @__PURE__ */ new Set(["runtime_lease_changed", "runtime_lease_stopped", "runtime_lease_destroyed"]);
@@ -575,6 +618,11 @@ var PUBLIC_API_ERRORS = {
   org_invitation_invalid: { family: "access", status: 409, message: "Invitation is invalid or unavailable" },
   org_invitation_pending: { family: "access", status: 409, message: "An invitation to this address is already pending" },
   org_invitation_rate_limited: { family: "access", status: 429, message: "Organization invitation limit exceeded" },
+  org_limit_reached: { family: "access", status: 403, message: "An account owns at most 3 organizations" },
+  org_creation_rate_limited: { family: "access", status: 429, message: "Organization creation limit exceeded" },
+  project_limit_reached: { family: "access", status: 402, message: "Free accounts have 3 projects. Get Cloud or Self-host for unlimited projects." },
+  seats_full: { family: "access", status: 402, message: "Add teammate seats to invite more people." },
+  email_verification_required: { family: "access", status: 403, message: "A verified email address is required" },
   org_invitation_email_mismatch: { family: "access", status: 403, message: "Sign in with the invited verified email address" },
   org_invitation_delivery_unavailable: { family: "access", status: 503, message: "Invitation delivery is unavailable" },
   team_not_found: { family: "access", status: 404, message: "Team not found" },
@@ -584,6 +632,12 @@ var PUBLIC_API_ERRORS = {
   project_member_not_found: { family: "access", status: 404, message: "Project member not found" },
   project_member_owner_immutable: { family: "access", status: 409, message: "The project owner's access cannot be changed" },
   resource_conflict: { family: "access", status: 409, message: "Organization or team authority changed concurrently" },
+  org_not_deletable: { family: "access", status: 409, message: "A personal organization goes with its account, and a deployment's with the deployment" },
+  org_has_workspaces: { family: "access", status: 409, message: "Delete the organization's workspaces first" },
+  account_owns_workspaces: { family: "access", status: 409, message: "Delete your workspaces first" },
+  account_founds_organization: { family: "access", status: 409, message: "Delete the organizations you founded first" },
+  account_has_cloud_subscription: { family: "access", status: 409, message: "Cancel Cloud before deleting this account" },
+  recent_sign_in_required: { family: "access", status: 403, message: "Sign in again to confirm this deletion" },
   session_not_found: { family: "session_share", status: 404, message: "This session is not on the control plane, so it cannot be shared from People yet." },
   session_share_admin_required: { family: "session_share", status: 403, message: "Only the person who started this session can manage its People." },
   session_share_target_required: { family: "session_share", status: 400, message: "A session is shared with exactly one person" },
@@ -607,11 +661,19 @@ var PUBLIC_API_ERRORS = {
   enrollment_paused: { status: 403, message: "enrollment_paused" },
   enrollment_owner_ineligible: { status: 403, message: "enrollment_owner_ineligible" },
   enrollment_key_version_mismatch: { status: 403, message: "enrollment_key_version_mismatch" },
+  enrollment_denied: { status: 403, message: "enrollment_denied" },
+  enrollment_approval_expired: { status: 403, message: "enrollment_approval_expired" },
+  enrollment_awaiting_approval: { status: 403, message: "enrollment_awaiting_approval" },
   invitation_invalid: { status: 403, message: "invitation_invalid" },
   invitation_expired: { status: 410, message: "invitation_expired" },
   invitation_revoked: { status: 410, message: "invitation_revoked" },
   invitation_redeemed: { status: 409, message: "invitation_redeemed" },
   invitation_host_conflict: { status: 409, message: "invitation_host_conflict" },
+  pairing_invalid: { status: 403, message: "pairing_invalid" },
+  pairing_expired: { status: 410, message: "pairing_expired" },
+  pairing_used: { status: 409, message: "pairing_used" },
+  pairing_owner_signed_out: { status: 410, message: "pairing_owner_signed_out" },
+  pairing_decided: { status: 409, message: "pairing_decided" },
   enrollment_generation_superseded: { status: 409, message: "enrollment_generation_superseded" },
   host_assignment_outside_scope: { status: 400, message: "host_assignment_outside_scope" },
   host_sealing_key_undeclared: { status: 409, message: "host_sealing_key_undeclared" },
@@ -779,7 +841,7 @@ var SANDBOX_MODEL_PROVIDER_HOSTS = [
   "api.openai.com",
   "generativelanguage.googleapis.com",
   "openrouter.ai",
-  // Model catalog + engine config, fetched on runner startup.
+  // The model catalog and engine config a runner fetches at startup.
   "models.dev",
   "opencode.ai"
 ];
@@ -865,13 +927,55 @@ async function refusedReason(leaseStore, workspaceId, epoch) {
   return "runtime_lease_not_serving";
 }
 
+// src/driver-ensure-input.ts
+function sandboxId(driver, workspaceId) {
+  return `${driver}-${workspaceId}`;
+}
+function leaseHostId(driver, workspaceId, lease, managerInput) {
+  return managerInput?.hostId ?? lease.hostId ?? sandboxId(driver.id, workspaceId);
+}
+function ensureHostInput(input) {
+  const egress = sandboxEgressDisposition(input.driver.metadata.egressControl, input.managerInput?.net, input.managerInput?.uncontainedEgress);
+  const labels = {
+    app: input.appLabel,
+    workspaceId: input.workspaceId,
+    epoch: String(input.lease.epoch),
+    homeRegion: input.homeRegion,
+    ...input.managerInput?.labels
+  };
+  return {
+    workspaceId: input.workspaceId,
+    hostId: leaseHostId(input.driver, input.workspaceId, input.lease, input.managerInput),
+    homeRegion: input.homeRegion,
+    epoch: input.lease.epoch,
+    labels,
+    bootSource: input.managerInput?.bootSource ?? (input.lease.checkpoint && input.lease.status !== "ready" && input.driver.metadata.persistence.resume === "replacement-restore" ? { kind: "driver-snapshot", snapshotId: input.lease.checkpoint.providerReference } : { kind: "default" }),
+    workspaceRoot: input.managerInput?.workspaceRoot ?? "/workspace",
+    runtimeCwd: input.managerInput?.runtimeCwd,
+    workspaceRuntimePort: input.managerInput?.workspaceRuntimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT,
+    env: { ...input.managerInput?.env, ...input.leaseEnv },
+    // Brokered secrets ride their own channel — NEVER merged into labels or env.
+    // Presence of the key, not its length, is the signal: `[]` is the caller
+    // withdrawing every brokered secret, and dropping it would reach the driver
+    // as "preserve what you have".
+    ...input.managerInput?.secrets ? { secrets: input.managerInput.secrets } : {},
+    source: input.managerInput?.source,
+    ...input.managerInput?.updateImage ? { updateImage: true } : {},
+    ...input.lease.machineClass ?? input.managerInput?.machineClass ? { machineClass: input.lease.machineClass ?? input.managerInput?.machineClass } : {},
+    exposure: input.managerInput?.exposure ?? (input.driver.metadata.targetAccess === "loopback" ? { kind: "loopback" } : { kind: "relay" }),
+    // Withheld where the start allows it, never downgraded: `undefined`
+    // here is the same shape a caller that asked for no containment produces,
+    // so the throwing drivers take their allow-all path and their throws stay
+    // intact for anyone who hands them a policy directly.
+    ...egress.action === "enforce" && input.managerInput?.net ? { net: sandboxNetworkPolicyWithBrokeredHosts(input.managerInput.net, input.managerInput.secrets) } : {},
+    snapshot: input.managerInput?.snapshot
+  };
+}
+
 // src/egress-warnings.ts
 function egressUnenforcedMessage(input) {
-  const scope = input.workspaceId ? `workspace ${input.workspaceId}` : "every sandbox it provisions";
-  const withheld = input.requested ? ` The requested allowlist (${(input.requested.hosts ?? []).length} host(s), ${(input.requested.cidrs ?? []).length} cidr(s)) was withheld, not applied.` : "";
-  return `[sandbox-manager] SANDBOX EGRESS IS UNRESTRICTED: driver "${input.driver}" declares egressControl: "none", so ${scope} can reach ANY host on the internet, including attacker-controlled buckets \u2014 agent-authored code inside the sandbox has an unmonitored exfiltration path.${withheld} Select a driver that can enforce egress (vercel) to close it. See public-docs/sandbox-egress.md.`;
+  return `[sandbox-manager] SANDBOX EGRESS IS UNRESTRICTED: driver "${input.driver}" declares egressControl: "none" and this start allows uncontained egress, so workspace ${input.workspaceId} can reach ANY host on the internet, including attacker-controlled buckets \u2014 agent-authored code inside the sandbox has an unmonitored exfiltration path. The requested allowlist (${(input.requested.hosts ?? []).length} host(s), ${(input.requested.cidrs ?? []).length} cidr(s)) was withheld, not applied. Select a driver that can enforce egress (cloudflare, vercel), or stop allowing uncontained egress so such starts are refused. See public-docs/sandbox-egress.md.`;
 }
-var compositionEgressWarnings = /* @__PURE__ */ new Set();
 var ensureEgressWarnings = /* @__PURE__ */ new Set();
 function defaultEgressUnenforcedSink(event) {
   console.warn(event.message);
@@ -880,26 +984,15 @@ function createEgressWarnings(input) {
   const { id, egressControl } = input.driver;
   const sink = input.sink ?? defaultEgressUnenforcedSink;
   const key = `${id}|${egressControl}`;
-  if (egressControl === "none" && !compositionEgressWarnings.has(key)) {
-    compositionEgressWarnings.add(key);
-    sink({
-      phase: "composition",
-      reason: "sandbox_egress_uncontained",
-      driver: id,
-      egressControl,
-      message: egressUnenforcedMessage({ phase: "composition", driver: id })
-    });
-  }
   return {
     withheld(start) {
       if (ensureEgressWarnings.has(key)) return;
       ensureEgressWarnings.add(key);
       sink({
-        phase: "ensure",
         reason: "sandbox_egress_uncontained",
         driver: id,
         egressControl,
-        message: egressUnenforcedMessage({ phase: "ensure", driver: id, workspaceId: start.workspaceId, requested: start.requested }),
+        message: egressUnenforcedMessage({ driver: id, workspaceId: start.workspaceId, requested: start.requested }),
         workspaceId: start.workspaceId,
         ...start.labels ? { labels: start.labels } : {},
         requested: start.requested
@@ -908,6 +1001,51 @@ function createEgressWarnings(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);
+}
+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"
+]);
+
+// src/start-admission.ts
+function refusedStart(input) {
+  const { driver, workspaceId, start } = input;
+  const egress = sandboxEgressDisposition(driver.metadata.egressControl, start.net, start.uncontainedEgress);
+  if (egress.action === "withhold" && start.net) {
+    input.egressWarnings.withheld({ workspaceId, ...start.labels ? { labels: start.labels } : {}, requested: start.net });
+  }
+  if (egress.action === "refuse") {
+    const error = egress.reason === "sandbox_egress_uncontained" ? sandboxEgressUncontainedError(driver.id) : egress.reason;
+    return { status: "unavailable", error, homeRegion: start.homeRegion };
+  }
+  const identityConflicts = workspaceRuntimeIdentityEnvConflicts(start.env);
+  if (identityConflicts.length) {
+    return { status: "unavailable", error: `sandbox env cannot set runtime identity: ${identityConflicts.join(", ")}`, homeRegion: start.homeRegion };
+  }
+  if (start.machineClass && !driver.metadata.machineClasses?.includes(start.machineClass)) {
+    return { status: "unavailable", error: `sandbox_machine_class_unsupported: ${driver.id} has no ${start.machineClass} machines`, homeRegion: start.homeRegion };
+  }
+  return void 0;
+}
+
 // src/garbage-collect.ts
 async function sweepSandboxes(input) {
   const { driver, leaseStore, appLabel } = input;
@@ -997,13 +1135,15 @@ function createSandboxStartRecorder(options) {
      * lease as it ends, so a poller reading the lease mid-boot sees how far the
      * start has come. `opened` writes the epoch's `lease_decision` before the
      * driver runs, so a stop that lands mid-boot finds the boot it ends on the
-     * row. A serving lease is not starting. An epoch acquired with a start it
-     * continues has that start and no phase yet; one acquired without begins
-     * its own here.
+     * row. A serving lease is not starting, unless the step is a person's
+     * update, which is a start of its own on the same epoch. An epoch acquired
+     * with a start it continues has that start and no phase yet; one acquired
+     * without begins its own here.
      */
     observe(lease, input) {
-      if (lease.status === "ready") return void 0;
-      let progress = lease.start ?? { requestedAt: input.enteredAt, startedAt: input.enteredAt, bootMode: input.bootMode, markedAt: input.enteredAt, phases: [] };
+      if (lease.status === "ready" && !input.update) return void 0;
+      const begun = { requestedAt: input.enteredAt, startedAt: input.enteredAt, bootMode: input.bootMode, markedAt: input.enteredAt, phases: [] };
+      let progress = lease.status === "ready" ? begun : lease.start ?? begun;
       const ended = [];
       let markedAt = progress.markedAt;
       const mark = (phase) => {
@@ -1109,74 +1249,8 @@ async function startSandboxFresh(input) {
   return { ok: true, status };
 }
 
-// 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);
-}
-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"
-]);
-
 // src/manager.ts
 var DEFAULT_APP_LABEL = "claxedo";
-function sandboxId(driver, workspaceId) {
-  return `${driver}-${workspaceId}`;
-}
-function leaseHostId(driver, workspaceId, lease, managerInput) {
-  return managerInput?.hostId ?? lease.hostId ?? sandboxId(driver.id, workspaceId);
-}
-function ensureHostInput(input) {
-  const egress = sandboxEgressDisposition(input.driver.metadata.egressControl, input.managerInput?.net);
-  const labels = {
-    app: input.appLabel,
-    workspaceId: input.workspaceId,
-    epoch: String(input.lease.epoch),
-    homeRegion: input.homeRegion,
-    ...input.managerInput?.labels
-  };
-  return {
-    workspaceId: input.workspaceId,
-    hostId: leaseHostId(input.driver, input.workspaceId, input.lease, input.managerInput),
-    homeRegion: input.homeRegion,
-    epoch: input.lease.epoch,
-    labels,
-    bootSource: input.managerInput?.bootSource ?? (input.lease.checkpoint && input.lease.status !== "ready" && input.driver.metadata.persistence.resume === "replacement-restore" ? { kind: "driver-snapshot", snapshotId: input.lease.checkpoint.providerReference } : { kind: "default" }),
-    workspaceRoot: input.managerInput?.workspaceRoot ?? "/workspace",
-    runtimeCwd: input.managerInput?.runtimeCwd,
-    workspaceRuntimePort: input.managerInput?.workspaceRuntimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT,
-    env: { ...input.managerInput?.env, ...input.leaseEnv },
-    // Brokered secrets ride their own channel — NEVER merged into labels or env.
-    // Presence of the key, not its length, is the signal: `[]` is the caller
-    // withdrawing every brokered secret, and dropping it would reach the driver
-    // as "preserve what you have".
-    ...input.managerInput?.secrets ? { secrets: input.managerInput.secrets } : {},
-    source: input.managerInput?.source,
-    ...input.lease.machineClass ?? input.managerInput?.machineClass ? { machineClass: input.lease.machineClass ?? input.managerInput?.machineClass } : {},
-    exposure: input.managerInput?.exposure ?? (input.driver.metadata.targetAccess === "loopback" ? { kind: "loopback" } : { kind: "relay" }),
-    // Withheld, never downgraded: `undefined` here is the same shape a caller
-    // that asked for no containment produces, so the throwing drivers take
-    // their allow-all path and their throws stay intact for anyone who hands
-    // them a policy directly.
-    ...egress.action === "enforce" && input.managerInput?.net ? { net: sandboxNetworkPolicyWithBrokeredHosts(input.managerInput.net, input.managerInput.secrets) } : {},
-    snapshot: input.managerInput?.snapshot
-  };
-}
 function createSandboxManager(options) {
   const persistence = validateSandboxPersistenceCapabilities(options.driver.metadata.persistence);
   if (!persistence.valid) throw new Error(`Invalid sandbox persistence capabilities: ${persistence.reason}`);
@@ -1286,7 +1360,7 @@ function createSandboxManager(options) {
       }
       const resuming = Boolean(lease.sandboxId && ensure.bootSource?.kind === "default" && options.driver.resumeHost);
       const bootMode = resuming && lease.url ? "resume" : ensure.bootSource?.kind === "driver-snapshot" ? "restore" : "cold-start";
-      const start = starts.observe(lease, { bootMode, enteredAt, labels: ensure.labels });
+      const start = starts.observe(lease, { bootMode, enteredAt, labels: ensure.labels, ...managerInput.updateImage ? { update: true } : {} });
       await start?.opened();
       ensure.onResource = async (resource) => {
         const recorded = await options.leaseStore.recordTarget(workspaceId, lease.epoch, {
@@ -1352,6 +1426,10 @@ function createSandboxManager(options) {
       const error = checkpointUnusable ? sandboxCheckpointUnusableError(checkpointUnusable, message) : bootFailed ? sandboxRuntimeBootFailedError(message) : startLimit ? sandboxProviderRateLimitedError(options.driver.id, startLimit) : isSandboxProviderKeyRefused(err) ? sandboxProviderKeyRefusedError(options.driver.id, message) : isSandboxStartRefusal(err) || sandboxLeaseEndedUnderStart(message) ? message : sandboxProviderFailedError(options.driver.id, message);
       if (lease.status === "ready" && !bootFailed) {
         const updated = await options.leaseStore.update(workspaceId, lease.epoch, { lastError: error }, "ready");
+        if (managerInput.updateImage) {
+          console.warn("A workspace's update to the deployment's image failed; it keeps serving its image", { workspaceId, epoch: lease.epoch, error });
+          return { status: "unavailable", error: isSandboxImageDownloadFailure(err) ? SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED : error, epoch: lease.epoch, homeRegion };
+        }
         if (updated) {
           const resolved = await leaseTarget(updated);
           if (resolved.status === "ready") return { ...resolved, stale: true };
@@ -1482,24 +1560,8 @@ function createSandboxManager(options) {
     return lease.sandboxId ? lease.nextRetryAt !== void 0 || stale : lease.nextRetryAt !== void 0 && !stale;
   }
   async function admit(workspaceId, input) {
-    const egress = sandboxEgressDisposition(options.driver.metadata.egressControl, input.net);
-    if (egress.action === "withhold" && input.net) {
-      egressWarnings.withheld({ workspaceId, ...input.labels ? { labels: input.labels } : {}, requested: input.net });
-    }
-    if (egress.action === "refuse") {
-      return { status: "unavailable", error: egress.reason, homeRegion: input.homeRegion };
-    }
-    const identityConflicts = workspaceRuntimeIdentityEnvConflicts(input.env);
-    if (identityConflicts.length) {
-      return {
-        status: "unavailable",
-        error: `sandbox env cannot set runtime identity: ${identityConflicts.join(", ")}`,
-        homeRegion: input.homeRegion
-      };
-    }
-    if (input.machineClass && !options.driver.metadata.machineClasses?.includes(input.machineClass)) {
-      return { status: "unavailable", error: `sandbox_machine_class_unsupported: ${options.driver.id} has no ${input.machineClass} machines`, homeRegion: input.homeRegion };
-    }
+    const refused = refusedStart({ driver: options.driver, workspaceId, start: input, egressWarnings });
+    if (refused) return refused;
     const existing = await options.leaseStore.get(workspaceId);
     const wait = waiting(existing);
     if (wait) return wait;
@@ -1698,12 +1760,16 @@ export {
   SANDBOX_RETRY_CAP_EXCEEDED,
   SANDBOX_RUNTIME_UNHEALTHY,
   SANDBOX_START_WINDOWS,
+  SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED,
   SandboxCheckpointUnusableError,
   SandboxHostGoneError,
+  SandboxImageDownloadError,
   SandboxProviderKeyRefusedError,
   SandboxProviderRateLimitedError,
   SandboxRuntimeBootError,
   SandboxStartRefusedError,
+  agent37Billing,
+  agent37MachineShapes,
   applySandboxLeaseFailure,
   applySandboxLeasePatch,
   applySandboxProvisionedTarget,
@@ -1719,6 +1785,7 @@ export {
   isSandboxCheckpointUnusable,
   isSandboxCheckpointUnusableCause,
   isSandboxHostGone,
+  isSandboxImageDownloadFailure,
   isSandboxListingUnsupported,
   isSandboxProviderKeyRefused,
   isSandboxProviderRateLimited,
@@ -1731,6 +1798,7 @@ export {
   sandboxCheckpointUnusableCauses,
   sandboxCheckpointUnusableError,
   sandboxEgressDisposition,
+  sandboxEgressUncontainedError,
   sandboxHostGoneError,
   sandboxLeaseEndedUnderStart,
   sandboxLeaseFailure,

package/dist/json.d.ts

@@ -1,13 +1,4 @@
-/**
- * Reading untrusted JSON: driver API responses, CLI output, stored records.
- *
- * Drivers all face the same problem — a provider hands back `any`, and the code
- * needs a few named fields out of it. Narrowing through these keeps the check
- * and the type in the same place, instead of each site asserting a shape it
- * never verified. The object check is `@claxedo/helpers/guards`, re-exported
- * under the names the drivers use.
- */
 export { asRecord as record, isRecord } from "@claxedo/helpers/guards";
-/** A non-empty string, or undefined — the shape almost every provider field wants. */
+/** An empty string is absent. */
 export declare function text(input: unknown): string | undefined;
 export declare function num(input: unknown): number | undefined;

package/dist/lease-failure.d.ts

@@ -15,6 +15,23 @@ export declare class SandboxRuntimeBootError extends Error implements SandboxRun
     readonly runtimeBootFailed: true;
     constructor(reason: string);
 }
+/**
+ * A driver throws this shape when the image a start pulls did not finish
+ * downloading because the registry link kept breaking. Nothing the machine
+ * served has changed, so an update that fails this way leaves the workspace
+ * serving its image.
+ */
+export type SandboxImageDownloadFailure = {
+    imageDownloadFailed: true;
+    message: string;
+};
+export declare function isSandboxImageDownloadFailure(err: unknown): err is SandboxImageDownloadFailure;
+export declare class SandboxImageDownloadError extends Error implements SandboxImageDownloadFailure {
+    readonly imageDownloadFailed: true;
+    constructor(reason: string);
+}
+/** The answer to a person's update whose image download kept breaking; the lease keeps the provider's own text. */
+export declare const SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED = "update_download_interrupted";
 export { isSandboxCheckpointUnusableCause, sandboxCheckpointUnusableCauses, type SandboxCheckpointUnusableCause };
 /**
  * A driver throws this shape when the checkpoint a start restores cannot be
@@ -74,6 +91,8 @@ export declare class SandboxStartRefusedError extends Error implements SandboxSt
     readonly startRefused: true;
     constructor(reason: string);
 }
+/** The error a start answers when `driver` declares no egress control and the start does not allow uncontained egress. */
+export declare function sandboxEgressUncontainedError(driver: string): string;
 /** The error a lease keeps when `driver`'s provider refused its key; the driver's message stays for the operator. */
 export declare function sandboxProviderKeyRefusedError(driver: string, message: string): string;
 /** The error a lease keeps when `driver` failed at its provider; the driver's message, which names hosts, requests and provider codes, stays for the operator. */
@@ -127,7 +146,7 @@ export declare function workspaceRuntimeBootReason(diagnostic: string): string |
 /**
  * What a driver keeps of a runtime's log within `maxChars`. A Node stack
  * under the boot-failure line is longer than the bound a driver puts on the
- * tail (600 chars on Boat, 2026-10-15 staging), so a tail alone keeps the
+ * tail (600 chars on Boat), so a tail alone keeps the
  * frames and loses the one line that names the reason.
  */
 export declare function runtimeBootDiagnostic(log: string, maxChars: number): string;

package/dist/lease-types.d.ts

@@ -6,16 +6,7 @@ export type SandboxLeaseRow = {
     home_region?: string;
     epoch: number;
     status: SandboxLeaseRowStatus;
-    /**
-     * The id the driver was registered with, which is any string: the manager
-     * dispatches on whatever a composition registers (`stores/d1.test.ts`
-     * provisions one called `"test-provider"`), and every other type this value
-     * flows between — `SandboxLease["driver"]`, `SandboxLeaseAcquireInput["driver"]`,
-     * `SandboxTarget["driver"]["id"]` — is already `string`. Typing the row as the
-     * closed `SandboxDriverID` made it the odd one out and forced every store to
-     * assert into it. Narrow with `isSandboxDriverID` where a CATALOG entry is
-     * needed, which is the only place the closed set is the right question.
-     */
+    /** Any string: the manager dispatches on whatever a composition registers. Narrow with `isSandboxDriverID` where a catalog entry is needed. */
     driver: string;
     driver_resource_id: string | null;
     driver_snapshot_id: string | null;

package/dist/runtime-env.d.ts

@@ -8,6 +8,12 @@ export type WorkspaceRuntimeControlEnv = {
 export declare function workspaceRuntimeIdentityEnvConflicts(env: Record<string, string> | undefined): string[];
 export declare function assertWorkspaceRuntimeIdentityEnv(env: Record<string, string> | undefined): void;
 export declare function workspaceRuntimeBootSecrets(env: Record<string, string>): string[];
+/**
+ * `text` with every boot secret in it replaced. Redact before bounding the
+ * text, so a secret the bound would cut in half is already gone. Values
+ * shorter than the floor (ports, flags) are left readable.
+ */
+export declare function redactWorkspaceRuntimeBootSecrets(text: string, secrets: readonly string[]): string;
 export declare function workspaceRuntimeBootEnv(input: Parameters<typeof workspaceRuntimeTargetEnv>[0] & Parameters<typeof workspaceRuntimeSourceEnv>[0] & {
     env?: Record<string, string>;
     nativeHarness?: string;

package/dist/runtime-env.mjs

@@ -31,6 +31,10 @@ var WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS = /* @__PURE__ */ new Set([
 function workspaceRuntimeBootSecrets(env) {
   return Object.entries(env).flatMap(([key, value]) => WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS.has(key) ? [] : [value]);
 }
+var REDACTED_VALUE_MIN_LENGTH = 8;
+function redactWorkspaceRuntimeBootSecrets(text, secrets) {
+  return secrets.filter((secret) => secret.length >= REDACTED_VALUE_MIN_LENGTH).reduce((output, secret) => output.split(secret).join("[redacted]"), text);
+}
 function workspaceRuntimeBootEnv(input) {
   assertWorkspaceRuntimeIdentityEnv(input.env);
   const env = {
@@ -73,6 +77,7 @@ function workspaceRuntimeServiceExposureEnv(input) {
 }
 export {
   assertWorkspaceRuntimeIdentityEnv,
+  redactWorkspaceRuntimeBootSecrets,
   workspaceRuntimeBootEnv,
   workspaceRuntimeBootSecrets,
   workspaceRuntimeIdentityEnvConflicts,

package/dist/runtime-version.d.ts

@@ -1,10 +1,28 @@
 export declare function workspaceRuntimeVersion(): string;
 /**
- * The oldest workspace-runtime version a driver may restore a workspace's
- * snapshot into running again. A filesystem snapshot carries the runtime it
- * was taken with, so a fix to the runtime reaches a workspace that keeps
- * waking only when this rises. Raise it, together with the runtime version,
- * for a security-relevant runtime change alone: every snapshot below it is
- * refused and its person must start the workspace fresh.
+ * The oldest workspace-runtime version this control plane and relay serve, for
+ * every driver: a workspace's snapshot restored, or the older image a Boat wake
+ * keeps serving instead of waiting on the deployment's. A filesystem snapshot
+ * carries the runtime it was taken with, and a kept image the runtime it
+ * shipped, so a fix to the runtime reaches a workspace that keeps waking only
+ * when this rises. Below it a Cloudflare restore is refused and its person
+ * must start the workspace fresh, and a Boat wake boots the deployment's image.
+ *
+ * Raise it, and the workspace-runtime version with it in the same commit, for
+ * a runtime security fix or for a control-plane or relay contract an older
+ * runtime cannot speak, and name the first cloud image published at the new
+ * version: the version-skew suite (`bun run --cwd packages/harness flows:skew`)
+ * runs the current control plane and relay against exactly that image.
+ * Bumping the version with it keeps the comparison honest: every image below
+ * the new version was built before the change. What it does not cover: the
+ * images built after the floor's at the same version are trusted, not tested.
  */
-export declare const MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+export declare const SERVED_WORKSPACE_RUNTIME_FLOOR: {
+    readonly version: "0.10.1";
+    readonly image: "ghcr.io/kyashrathore/claxedo-sandbox:workspace-runtime-0-10-1-40706b7356-agent-plugins-v8";
+};
+export declare const MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION: "0.10.1";
+/** Where the sandbox image keeps the version of the runtime it ships, from the image's root. */
+export declare const SANDBOX_IMAGE_RUNTIME_VERSION_FILE = "opt/workspace-runtime/workspace-runtime-version";
+/** A shell test that passes when the runtime version in `file`, a shell word, is one this control plane serves. */
+export declare function servedRuntimeVersionTest(file: string): string;

package/dist/runtime-version.mjs

@@ -3,8 +3,19 @@ var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
 function workspaceRuntimeVersion() {
   return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
 }
-var MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+var SERVED_WORKSPACE_RUNTIME_FLOOR = {
+  version: "0.10.1",
+  image: "ghcr.io/kyashrathore/claxedo-sandbox:workspace-runtime-0-10-1-40706b7356-agent-plugins-v8"
+};
+var MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION = SERVED_WORKSPACE_RUNTIME_FLOOR.version;
+var SANDBOX_IMAGE_RUNTIME_VERSION_FILE = "opt/workspace-runtime/workspace-runtime-version";
+function servedRuntimeVersionTest(file) {
+  return `version=$(cat ${file} 2>/dev/null) && [ -n "$version" ] && [ "$(printf '%s\\n%s\\n' ${MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION} "$version" | sort -V | head -n 1)" = ${MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION} ]`;
+}
 export {
-  MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION,
+  MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION,
+  SANDBOX_IMAGE_RUNTIME_VERSION_FILE,
+  SERVED_WORKSPACE_RUNTIME_FLOOR,
+  servedRuntimeVersionTest,
   workspaceRuntimeVersion
 };