@claxedo/sandbox-manager 0.7.0 → 0.10.0

package/dist/drivers/boat-template.mjs

@@ -0,0 +1,1196 @@
+// src/drivers/boat-template.ts
+import { generateKeyPairSync } from "node:crypto";
+
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+
+// src/contract.ts
+var SANDBOX_IMAGE_LABEL = "image";
+
+// src/stores/memory.ts
+function sandboxLease(input) {
+  return {
+    workspaceId: input.workspaceId,
+    homeRegion: input.homeRegion ?? "us-east",
+    driver: input.driver ?? "test",
+    epoch: input.epoch ?? 1,
+    routingId: input.routingId,
+    status: input.status ?? "ready",
+    retryCount: input.retryCount ?? 0,
+    createdAt: input.createdAt ?? Date.now(),
+    updatedAt: input.updatedAt ?? Date.now(),
+    sandboxId: input.sandboxId,
+    url: input.url,
+    hostId: input.hostId,
+    driverResourceId: input.driverResourceId,
+    nextRetryAt: input.nextRetryAt,
+    lastError: input.lastError,
+    lastHeartbeatAt: input.lastHeartbeatAt,
+    lastActivityAt: input.lastActivityAt,
+    labels: input.labels,
+    checkpoint: input.checkpoint,
+    persistence: input.persistence,
+    restore: input.restore,
+    start: input.start,
+    machineClass: input.machineClass
+  };
+}
+
+// ../claxedo-helpers/dist/string.mjs
+function isString(value) {
+  return typeof value === "string";
+}
+function trimToUndefined(value) {
+  if (!isString(value))
+    return;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+
+// ../sandbox-contract/dist/index.mjs
+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"
+};
+
+// src/lease-failure.ts
+var SandboxRuntimeBootError = class extends Error {
+  runtimeBootFailed = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxRuntimeBootError";
+  }
+};
+var SandboxHostGoneError = class extends Error {
+  hostGone = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxHostGoneError";
+  }
+};
+var SANDBOX_START_WINDOWS = ["minute", "hour", "day"];
+var WORKSPACE_RUNTIME_BOOT_FAILED_LINE = "workspace_runtime_boot_failed: ";
+function workspaceRuntimeBootReason(diagnostic) {
+  const at = diagnostic.lastIndexOf(WORKSPACE_RUNTIME_BOOT_FAILED_LINE);
+  if (at < 0) return void 0;
+  const [reason = ""] = diagnostic.slice(at + WORKSPACE_RUNTIME_BOOT_FAILED_LINE.length).split(/\n\s+at /);
+  return reason.trim().replace(/^Error: /, "") || void 0;
+}
+function runtimeBootDiagnostic(log, maxChars) {
+  const trimmed = log.trim();
+  const reason = workspaceRuntimeBootReason(trimmed);
+  if (reason === void 0) return trimmed.slice(-maxChars);
+  return `${WORKSPACE_RUNTIME_BOOT_FAILED_LINE}${reason}`.slice(0, maxChars);
+}
+
+// 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 workspaceRuntimeBootSecrets(env) {
+  return Object.entries(env).flatMap(([key, value]) => WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS.has(key) ? [] : [value]);
+}
+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,
+    ...input.hostId ? { WORKSPACE_RUNTIME_HOST_ID: input.hostId } : {},
+    WORKSPACE_RUNTIME_DIRECTORY: input.directory,
+    WORKSPACE_RUNTIME_PORT: String(input.port),
+    ...input.host ? { WORKSPACE_RUNTIME_HOST: input.host } : {}
+  };
+}
+function workspaceRuntimeSourceEnv(input) {
+  if (!input.source || input.source.kind === "empty") return { WORKSPACE_RUNTIME_SOURCE_KIND: "empty" };
+  return {
+    WORKSPACE_RUNTIME_SOURCE_KIND: "git",
+    WORKSPACE_RUNTIME_GIT_REPO_URL: input.source.repoUrl,
+    ...input.source.branch ? { WORKSPACE_RUNTIME_GIT_BRANCH: input.source.branch } : {}
+  };
+}
+
+// src/command.ts
+function shell(input) {
+  return `'${input.replace(/'/g, `'"'"'`)}'`;
+}
+function envFile(input) {
+  return Object.entries(input).map(([key, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new Error(`environment variable ${JSON.stringify(key)} cannot be exported through an env file`);
+    }
+    return `export ${key}=${shell(value)}`;
+  }).join("\n") + "\n";
+}
+
+// src/image-name.ts
+function assertSandboxImageReference(image) {
+  if (!image || image !== image.trim() || image.startsWith("-") || /\s/.test(image)) {
+    throw new Error(`sandbox image reference is not a legal image identifier: ${JSON.stringify(image)}`);
+  }
+  return image;
+}
+
+// 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`
+};
+
+// src/driver-catalog.ts
+var sandboxDriverCatalog = {
+  modal: {
+    id: "modal",
+    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",
+      // The driver does not install Modal's domain allowlist or alpha sidecar.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  vercel: {
+    id: "vercel",
+    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",
+      // The driver translates hosts only; the SDK's subnet rules are not wired to net.cidrs.
+      egressControl: "hosts",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "stopped",
+        retention: "explicit",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  cloudflare: {
+    id: "cloudflare",
+    label: sandboxDriverLabels.cloudflare,
+    credentialFields: sandboxDriverCredentialFields.cloudflare,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
+    billing: cloudflareBilling,
+    metadata: {
+      driverRunsIn: ["worker"],
+      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: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  boat: {
+    id: "boat",
+    label: sandboxDriverLabels.boat,
+    credentialFields: sandboxDriverCredentialFields.boat,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
+    billing: boatBilling,
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: false,
+        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",
+      hostResumeBehavior: "same-host",
+      targetAccess: "loopback",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "same-resource",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
+  }
+};
+
+// ../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 num(input) {
+  return typeof input === "number" ? input : void 0;
+}
+
+// ../claxedo-helpers/dist/deadline.mjs
+async function withDeadlineSignal(timeoutMs, work, parent) {
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new DOMException("The operation timed out.", "TimeoutError")), timeoutMs);
+  try {
+    return await work(parent ? AbortSignal.any([parent, deadline.signal]) : deadline.signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/drivers/boat-client.ts
+var DEFAULT_BASE_URL = "https://boat.dev/api/v1";
+var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_COMMAND_SECONDS = 30;
+var COMMAND_RESPONSE_MARGIN_MS = 3e4;
+var START_HOLD_MS = 6e4;
+var STILL_STARTING_CODES = /* @__PURE__ */ new Set(["sandbox_starting", "boat_starting"]);
+var MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+var SANDBOX_STATES = /* @__PURE__ */ new Set(["init", "provisioning", "provisioned", "cloning", "ready", "idle", "running", "archiving", "archived", "error", "cancelled"]);
+var BoatApiError = class extends Error {
+  constructor(message, code, status, refusal = {}) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "BoatApiError";
+    this.providerKeyRefused = status === 401 || status === 403;
+    this.startLimit = refusal.startLimit;
+    this.sandboxState = refusal.sandboxState;
+    if (refusal.startLimit) this.providerRateLimited = { window: refusal.startLimit.window, limit: refusal.startLimit.limit };
+  }
+  /** Boat answers 401 or 403 to the API key itself, never to a sandbox it was asked about. */
+  providerKeyRefused;
+  /** Create, fork and resume each count as one start (Boat's own refusal, 2026-10-15). */
+  providerRateLimited;
+  startLimit;
+  /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed` (2026-10-17). */
+  sandboxState;
+};
+function startCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
+}
+function startLimitOf(body) {
+  const details = asRecord(asRecord(body?.error)?.details);
+  const window = SANDBOX_START_WINDOWS.find((name) => name === details?.window);
+  const limit = startCount(details?.limit);
+  if (!window || limit === void 0) return void 0;
+  const starts = asRecord(details?.starts);
+  return {
+    window,
+    limit,
+    starts: Object.fromEntries(SANDBOX_START_WINDOWS.flatMap((name) => {
+      const entry = asRecord(starts?.[name]);
+      const entryLimit = startCount(entry?.limit);
+      const used = startCount(entry?.used);
+      return entryLimit === void 0 || used === void 0 ? [] : [[name, { limit: entryLimit, used }]];
+    }))
+  };
+}
+function invalid() {
+  throw new BoatApiError("Boat API returned an invalid response", "invalid_response");
+}
+function requiredText(value) {
+  return typeof value === "string" ? value : invalid();
+}
+function requiredFlag(value) {
+  return typeof value === "boolean" ? value : invalid();
+}
+function commandExitCode(value) {
+  return value === null ? null : typeof value === "number" && Number.isSafeInteger(value) ? value : invalid();
+}
+function isSandboxState(value) {
+  return typeof value === "string" && SANDBOX_STATES.has(value);
+}
+function sandbox(body) {
+  const value = asRecord(body.sandbox) ?? invalid();
+  const id = requiredText(value.id);
+  if (!/^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$/.test(id) || !isSandboxState(value.state)) invalid();
+  return { id, state: value.state, hydrated: value.hydrated === true };
+}
+async function readBoundedResponseJson(response) {
+  const reader = response.body?.getReader() ?? invalid();
+  const decoder = new TextDecoder();
+  let text = "";
+  let size = 0;
+  for (let next = await reader.read(); !next.done; next = await reader.read()) {
+    size += next.value.byteLength;
+    if (size > MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      invalid();
+    }
+    text += decoder.decode(next.value, { stream: true });
+  }
+  return asRecord(JSON.parse(text + decoder.decode()));
+}
+function createBoatApi(options) {
+  const base = new URL(options.baseUrl ?? DEFAULT_BASE_URL);
+  if (base.protocol !== "https:" || base.username || base.password || base.search || base.hash) {
+    throw new Error("Boat endpoint requires HTTPS without credentials, query or fragment");
+  }
+  const baseUrl = base.href.replace(/\/+$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+  async function api(path, types, init) {
+    return withDeadlineSignal(init?.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS, async (signal) => {
+      let response;
+      try {
+        response = await fetchImpl(`${baseUrl}${path}`, {
+          method: init?.method ?? "GET",
+          redirect: "manual",
+          headers: {
+            Authorization: `Bearer ${options.apiKey}`,
+            ...init?.body === void 0 ? {} : { "Content-Type": "application/json" },
+            ...init?.headers
+          },
+          ...init?.body === void 0 ? {} : { body: JSON.stringify(init.body) },
+          signal
+        });
+      } catch {
+        throw new BoatApiError(`Boat ${init?.method ?? "GET"} ${path} failed before acknowledgement`, "transport_failed");
+      }
+      const body = await readBoundedResponseJson(response).catch(() => void 0);
+      if (!response.ok || body?.ok === false) {
+        const code = typeof body?.code === "string" ? body.code : `http_${response.status}`;
+        const startLimit = response.status === 429 && code === "rate_limited" ? startLimitOf(body) : void 0;
+        const sandboxState = asRecord(asRecord(asRecord(body?.error)?.details)?.sandbox)?.state;
+        throw new BoatApiError(`Boat ${init?.method ?? "GET"} ${path} was rejected (${code})`, code, response.status, {
+          startLimit,
+          sandboxState: isSandboxState(sandboxState) ? sandboxState : void 0
+        });
+      }
+      if (body?.ok !== true || typeof body.type !== "string" || !types.includes(body.type)) {
+        const answered = typeof body?.type === "string" ? `"${body.type}"` : "no envelope type";
+        throw new BoatApiError(`Boat ${init?.method ?? "GET"} ${path} answered ${answered}, expected ${types.join(" or ")}`, "invalid_response");
+      }
+      return body;
+    });
+  }
+  return api;
+}
+function createBoatClient(options) {
+  const api = createBoatApi(options);
+  const path = (id) => `/sandboxes/${encodeURIComponent(id)}`;
+  return {
+    /** `from` is a named snapshot or a share code (`bsh_…`) the sandbox starts from; omitted, Boat's base machine. */
+    async create(input) {
+      return sandbox(await api("/sandboxes", ["sandbox.created"], {
+        method: "POST",
+        body: { noEnv: true, ttlSeconds: input.ttlSeconds, ...input.type ? { type: input.type } : {}, ...input.from ? { from: input.from } : {} },
+        headers: { "Idempotency-Key": input.idempotencyKey }
+      }));
+    },
+    async get(id) {
+      const value = sandbox(await api(path(id), ["sandbox.info"]));
+      return value.id === id ? value : invalid();
+    },
+    /** `type` resumes the sandbox onto that machine size; omitted, it keeps the size it has (docs.boat.dev/machines/change-size). */
+    async resume(id, input) {
+      await api(`${path(id)}/resume`, ["sandbox.resuming"], {
+        method: "POST",
+        body: { noEnv: true, ttlSeconds: input.ttlSeconds, ...input.type ? { type: input.type } : {} }
+      });
+    },
+    /**
+     * `ttlSeconds` sets the auto-stop deadline to now plus that many seconds; `null` removes it.
+     * Boat's reference example answers `sandbox.info`; the API answers `sandbox.updated` (2026-10-13).
+     */
+    async update(id, input) {
+      const value = sandbox(await api(path(id), ["sandbox.updated", "sandbox.info"], { method: "PATCH", body: input }));
+      return value.id === id ? value : invalid();
+    },
+    async stop(id) {
+      await api(`${path(id)}/stop`, ["sandbox.stopping"], { method: "POST" });
+    },
+    async delete(id) {
+      await api(path(id), ["sandbox.deleting", "deletion.operation"], { method: "DELETE", headers: { "X-Ascii-Confirm-Delete": id } });
+    },
+    async writeFile(id, input) {
+      const body = await api(`${path(id)}/files`, ["file.written"], { method: "PUT", body: { ...input, encoding: "utf8" } });
+      if (body.success !== true) invalid();
+    },
+    /** `ready` once a command runs, which Boat answers the moment the sandbox is ready; `starting` when Boat's hold ended first. */
+    async whenReady(id) {
+      try {
+        await api(`${path(id)}/commands`, ["command.finished"], {
+          method: "POST",
+          body: { command: "true", timeoutSeconds: 1 },
+          timeoutMs: START_HOLD_MS + COMMAND_RESPONSE_MARGIN_MS
+        });
+        return "ready";
+      } catch (err) {
+        if (err instanceof BoatApiError && STILL_STARTING_CODES.has(err.code)) return "starting";
+        throw err;
+      }
+    },
+    async command(id, input) {
+      const timeoutMs = (input.timeoutSeconds ?? DEFAULT_COMMAND_SECONDS) * 1e3 + COMMAND_RESPONSE_MARGIN_MS;
+      const body = await api(`${path(id)}/commands`, ["command.finished"], { method: "POST", body: input, timeoutMs });
+      return {
+        success: requiredFlag(body.success),
+        stdout: requiredText(body.stdout),
+        stderr: requiredText(body.stderr),
+        exitCode: commandExitCode(body.exitCode),
+        timedOut: requiredFlag(body.timedOut)
+      };
+    }
+  };
+}
+
+// src/drivers/transient-error.ts
+function textOf(input) {
+  return typeof input === "string" ? input : "";
+}
+function driverErrorSignals(err) {
+  const shaped = isRecord(err) ? err : {};
+  const nested = isRecord(shaped.response) ? shaped.response : {};
+  return {
+    // `response.status` is the axios shape; `statusCode` is what SDK-native
+    // error classes expose instead.
+    status: num(nested.status) ?? num(shaped.status) ?? num(shaped.statusCode),
+    text: `${textOf(shaped.code)} ${textOf(shaped.name)} ${textOf(shaped.message)}`.toLowerCase()
+  };
+}
+function isTransientDriverError(err, markers) {
+  const { status, text } = driverErrorSignals(err);
+  if (status !== void 0 && status >= 500) return true;
+  return markers.some((marker) => text.includes(marker));
+}
+var TRANSIENT_DRIVER_RETRY_MS = 2e3;
+
+// src/drivers/boat.ts
+var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
+var DEFAULT_WORKSPACE_DIR = "/workspace";
+var DEFAULT_CONTAINER_NAME = "claxedo-runtime";
+var DEFAULT_PROVISION_TIMEOUT_MS = 12e4;
+var DEFAULT_STATE_POLL_MS = { firstMs: 250, maxMs: 2e3 };
+var DEFAULT_HEALTH_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_HEALTH_INTERVAL_MS = 100;
+var HEALTH_PROBE_WINDOW_SECONDS = 50;
+var HEALTH_PROBE_MARGIN_SECONDS = 10;
+var BOOTING_CONTAINER_STATES = /* @__PURE__ */ new Set(["running", "paused"]);
+var IMAGE_PREPARATION_TIMEOUT_SECONDS = 600;
+var CONTAINER_START_TIMEOUT_SECONDS = 120;
+var HOST_PUBLISH_TIMEOUT_SECONDS = 120;
+var BOOT_TTL_SECONDS = 30 * 60;
+var DOCKER_DAEMON_WAIT_SECONDS = 120;
+var RUNTIME_ENV_PATH = ".claxedo-runtime-env";
+var REGISTRY_PASSWORD_PATH = ".claxedo-registry-password";
+var BOOT_LOCK_PATH = "/run/lock/claxedo-boot.lock";
+var BOOT_LOCK_HEADROOM_SECONDS = 60;
+var CONTAINER_ENV_PATH = "/run/claxedo-runtime.env";
+var PERSISTENT_ROOT = "claxedo-persistent";
+var PERSISTENT_HOME_MOUNTS = [["claxedo", "/root/.claxedo"], ["workspace-runtime", "/root/.workspace-runtime"]];
+var IMAGE_TREES = ["root", "usr", "etc", "var", "opt", "home", "srv"];
+var IMAGE_TREE_SEED_EXCLUDES = ["root/.cache", "root/.npm/_cacache"];
+var IMAGE_TREES_COMPLETE_MARKER = ".complete";
+var SEED_CONTAINER_NAME = "claxedo-seed";
+var STUB_IMAGE = "claxedo-runtime-stub";
+var STUB_IMAGE_ARCHIVE = "stub.tar";
+var IMAGE_LABEL = "claxedo.image";
+var IMAGE_ENV_FILE = "image.env";
+var ROOT_LINKS = ["bin", "lib", "lib64", "sbin"];
+var ROOT_DIRECTORIES = ["boot", "dev", "media", "mnt", "proc", "run", "sys", "tmp", ...IMAGE_TREES];
+var BOAT_SAVED_IMAGES = "/var/lib/ascii-docker-images";
+var BOAT_CONTAINER_RECORD = "/etc/ascii-docker.json";
+var DOCKER_NAME_IN_USE = "is already in use by container";
+var CONTAINER_CREATE_ATTEMPTS = 5;
+var CONTAINER_SECURITY_OPTIONS = "--security-opt seccomp=unconfined --security-opt apparmor=unconfined";
+var VM_DOCKER_INIT = "/usr/libexec/docker/docker-init";
+var CONTAINER_INIT_PATH = "/claxedo-init";
+var CONTAINER_STOP_GRACE_SECONDS = 30;
+var HOST_RELAY_NOT_STOPPED = "The sandbox could not stop the localhost relay of this port. Try again.";
+var STDERR_TAIL_CHARS = 600;
+var REDACTED_VALUE_MIN_LENGTH = 8;
+var READY_STATES = /* @__PURE__ */ new Set(["ready", "idle", "running"]);
+var PENDING_STATES = /* @__PURE__ */ new Set(["init", "provisioning", "provisioned", "cloning"]);
+var TRANSIENT_MARKERS = ["transport_failed", "idempotency_in_progress"];
+var GONE_CODES = /* @__PURE__ */ new Set(["not_found", "snapshot_data_expired"]);
+var RESUME_UNDER_WAY = "sandbox_resuming";
+var NOT_RUNNING_CODES = /* @__PURE__ */ new Set(["machine_not_running", "sandbox_not_ready"]);
+var TEMPLATE_UNREADABLE_CODES = /* @__PURE__ */ new Set(["snapshot_not_found", "api_key_action_forbidden", "api_key_sandbox_forbidden"]);
+function boatTemplateResetCommand() {
+  const bootFiles = [
+    `${PERSISTENT_ROOT}/workspace`,
+    ...PERSISTENT_HOME_MOUNTS.map(([source]) => `${PERSISTENT_ROOT}/${source}`),
+    RUNTIME_ENV_PATH,
+    `${RUNTIME_ENV_PATH}.*`,
+    `${REGISTRY_PASSWORD_PATH}.*`
+  ];
+  return `{ docker rm -f ${DEFAULT_CONTAINER_NAME} >/dev/null 2>&1 || true; } && sudo rm -rf ${bootFiles.join(" ")} && [ -z "$(docker ps -aq)" ] && echo '[]' | sudo tee ${BOAT_CONTAINER_RECORD} >/dev/null && sudo find ${BOAT_SAVED_IMAGES} -mindepth 1 -delete && ls -d ${PERSISTENT_ROOT}/image-*/${IMAGE_TREES_COMPLETE_MARKER}`;
+}
+function hostGoneOrThrow(err) {
+  if (err instanceof BoatApiError && GONE_CODES.has(err.code)) throw new SandboxHostGoneError(err.message);
+  throw err;
+}
+function notRunningOrThrow(err) {
+  if (err instanceof BoatApiError && NOT_RUNNING_CODES.has(err.code)) return;
+  hostGoneOrThrow(err);
+}
+function archivedOrThrow(err) {
+  if (err instanceof BoatApiError && err.code === "stop_failed" && err.sandboxState === "archived") return;
+  hostGoneOrThrow(err);
+}
+function holdingBootLock(commandTimeoutSeconds, script) {
+  const wait = commandTimeoutSeconds - BOOT_LOCK_HEADROOM_SECONDS;
+  return `exec 9>>${BOOT_LOCK_PATH} && { flock -w ${wait} 9 || { echo "another boot of this machine held ${BOOT_LOCK_PATH} for ${wait} s" >&2; exit 1; }; } && ${script}`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function scrubbed(text, secrets) {
+  return secrets.filter((secret) => secret.length >= REDACTED_VALUE_MIN_LENGTH).reduce((output, secret) => output.split(secret).join("[redacted]"), text);
+}
+function scrubbedTail(text, secrets) {
+  return scrubbed(text, secrets).trim().slice(-STDERR_TAIL_CHARS);
+}
+function imageTreesDirectory(image) {
+  return `image-${image.replace(/[^A-Za-z0-9._-]/g, "-")}`;
+}
+function containerHostname(workspaceId) {
+  return workspaceId.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").slice(0, 63) || "claxedo";
+}
+var BoatDriverError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BoatDriverError";
+  }
+};
+function createBoatSandboxDriver(options) {
+  const client = createBoatClient({
+    apiKey: options.apiKey,
+    ...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+    ...options.operationTimeoutMs ? { timeoutMs: options.operationTimeoutMs } : {},
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  });
+  const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
+  const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
+  const containerName = options.containerName ?? DEFAULT_CONTAINER_NAME;
+  const provisionTimeoutMs = options.provisionTimeoutMs ?? DEFAULT_PROVISION_TIMEOUT_MS;
+  const statePollMs = options.statePollMs ?? DEFAULT_STATE_POLL_MS;
+  const healthTimeoutMs = options.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  const healthIntervalMs = options.healthIntervalMs ?? DEFAULT_HEALTH_INTERVAL_MS;
+  function runtimePort(input) {
+    return input.workspaceRuntimePort ?? options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
+  }
+  function workspaceDirectory(input) {
+    return input.workspaceRoot ?? workspaceDir;
+  }
+  function resolveImage(input) {
+    return assertSandboxImageReference(
+      input.bootSource?.kind === "image" ? input.bootSource.image : input.snapshot ?? options.image
+    );
+  }
+  function bootEnv(input, hostId) {
+    return workspaceRuntimeBootEnv({
+      workspaceId: input.workspaceId,
+      hostId,
+      directory: workspaceDirectory(input),
+      port: runtimePort(input),
+      host: "0.0.0.0",
+      source: input.source,
+      env: input.env,
+      nativeHarness: options.nativeHarness,
+      controlEnv: options.controlEnv
+    });
+  }
+  async function execOrThrow(sandboxId, command, label, input = {}) {
+    const send = () => client.command(sandboxId, { command, ...input.timeoutSeconds ? { timeoutSeconds: input.timeoutSeconds } : {} });
+    let result = await send();
+    if (input.retryOnceOn && result.exitCode !== 0 && result.stderr.includes(input.retryOnceOn)) result = await send();
+    if (result.timedOut || result.exitCode !== 0) {
+      const outcome = result.timedOut ? "timed out" : `failed (exit ${result.exitCode ?? "signal"})`;
+      const stderr = scrubbedTail(result.stderr, input.secrets ?? []);
+      throw new BoatDriverError(`Boat ${sandboxId} ${label} ${outcome}${stderr ? `: ${stderr}` : ""}`);
+    }
+    return result;
+  }
+  async function waitUntilReady(sandboxId) {
+    const until = Date.now() + provisionTimeoutMs;
+    for (; ; ) {
+      const answer = await client.whenReady(sandboxId).catch(async (err) => {
+        if (!(err instanceof BoatApiError && NOT_RUNNING_CODES.has(err.code))) hostGoneOrThrow(err);
+        const { state } = await client.get(sandboxId).catch(hostGoneOrThrow);
+        if (!READY_STATES.has(state) && !PENDING_STATES.has(state)) throw new BoatDriverError(`Boat ${sandboxId} entered non-ready state: ${state}`);
+        await sleep(statePollMs.maxMs);
+        return "starting";
+      });
+      if (answer === "ready") return true;
+      if (Date.now() >= until) return false;
+    }
+  }
+  async function stateAfterArchiving(sandboxId) {
+    const until = Date.now() + provisionTimeoutMs;
+    let wait = statePollMs.firstMs;
+    for (; ; ) {
+      const { state } = await client.get(sandboxId).catch(hostGoneOrThrow);
+      if (state !== "archiving") return state;
+      if (Date.now() >= until) return void 0;
+      await sleep(wait);
+      wait = Math.min(wait * 2, statePollMs.maxMs);
+    }
+  }
+  function containerScripts(input, staged) {
+    const port = runtimePort(input);
+    const directory = workspaceDirectory(input);
+    const reference = resolveImage(input);
+    const image = shell(reference);
+    const trees = `"$(pwd)/${PERSISTENT_ROOT}/${imageTreesDirectory(reference)}"`;
+    const labelledWithImage = (object, name) => `[ "$(docker ${object} inspect --format '{{index .Config.Labels "${IMAGE_LABEL}"}}' ${name} 2>/dev/null)" = ${image} ]`;
+    const bootScript = [
+      `. ${CONTAINER_ENV_PATH}`,
+      `mkdir -p ${shell(directory)}`,
+      `cd ${shell(directory)}`,
+      `exec ${runtimeCommand}`
+    ].join(" && ");
+    const mounts = [["workspace", directory], ...PERSISTENT_HOME_MOUNTS];
+    const run = `docker run -d --name ${containerName} --hostname ${shell(containerHostname(input.workspaceId))} -p ${port}:${port} -v ${VM_DOCKER_INIT}:${CONTAINER_INIT_PATH}:ro -v "$(pwd)/${RUNTIME_ENV_PATH}:${CONTAINER_ENV_PATH}:ro" --env-file ${trees}/${IMAGE_ENV_FILE} ` + IMAGE_TREES.map((tree) => `-v ${trees}/${tree}:/${tree} `).join("") + mounts.map(([source, target]) => `-v "$(pwd)/${PERSISTENT_ROOT}/${source}":${shell(target)} `).join("") + `${CONTAINER_SECURITY_OPTIONS} --entrypoint ${CONTAINER_INIT_PATH} ${STUB_IMAGE} -- sh -lc ${shell(bootScript)}`;
+    const seedTrees = `sudo rm -rf ${trees} && sudo mkdir -p ${trees} && { docker rm -f ${SEED_CONTAINER_NAME} >/dev/null 2>&1 || true; } && docker create --name ${SEED_CONTAINER_NAME} ${image} true >/dev/null && for tree in ${IMAGE_TREES.join(" ")}; do docker cp ${SEED_CONTAINER_NAME}:/$tree - | sudo tar -xf - -C ${trees} ${IMAGE_TREE_SEED_EXCLUDES.map((exclude) => `--exclude=${exclude}`).join(" ")} && [ -d ${trees}/$tree ] || exit 1; done && docker rm ${SEED_CONTAINER_NAME} >/dev/null && sudo touch ${trees}/${IMAGE_TREES_COMPLETE_MARKER}`;
+    const seedStub = `stub=$(mktemp -d) && docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' ${image} > "$stub/${IMAGE_ENV_FILE}" && workdir=$(docker image inspect --format '{{or .Config.WorkingDir "/"}}' ${image}) && mkdir "$stub/root" ${ROOT_DIRECTORIES.map((directory2) => `"$stub/root/${directory2}"`).join(" ")} && ${ROOT_LINKS.map((link) => `ln -s usr/${link} "$stub/root/${link}"`).join(" && ")} && chmod 1777 "$stub/root/tmp" && tar --owner=0 --group=0 --numeric-owner -cf "$stub/skeleton.tar" -C "$stub/root" . && docker import --change "WORKDIR $workdir" --change ${shell(`LABEL ${IMAGE_LABEL}=${reference}`)} "$stub/skeleton.tar" ${STUB_IMAGE} >/dev/null && docker save -o "$stub/${STUB_IMAGE_ARCHIVE}" ${STUB_IMAGE} && sudo mv "$stub/${IMAGE_ENV_FILE}" "$stub/${STUB_IMAGE_ARCHIVE}" ${trees}/ && rm -rf "$stub"`;
+    const removeImage = `if docker image inspect ${image} >/dev/null 2>&1; then leftovers=$(docker ps -aq --filter ancestor=${image}) && { [ -z "$leftovers" ] || docker rm -f $leftovers >/dev/null; } && id=$(docker image inspect --format '{{.Id}}' ${image}) && docker rmi ${image} >/dev/null && sudo rm -f ${BOAT_SAVED_IMAGES}/"\${id#sha256:}".tar; fi`;
+    const seeded = [IMAGE_TREES_COMPLETE_MARKER, STUB_IMAGE_ARCHIVE, IMAGE_ENV_FILE].map((file) => `[ -f ${trees}/${file} ]`).join(" && ");
+    const prepare = [
+      `chmod 600 ${staged.env}`,
+      `find . -maxdepth 1 \\( -name '${RUNTIME_ENV_PATH}.*' -o -name '${REGISTRY_PASSWORD_PATH}.*' \\) -mmin +${BOOT_TTL_SECONDS / 60} -exec rm -f {} +`,
+      `timeout ${DOCKER_DAEMON_WAIT_SECONDS} sh -c 'until docker info >/dev/null 2>&1; do sleep 1; done'`,
+      `[ -x ${VM_DOCKER_INIT} ]`,
+      ...options.registryAuth && staged.password ? [`{ chmod 600 ${staged.password}; docker login ${shell(options.registryAuth.server)} --username ${shell(options.registryAuth.username)} --password-stdin < ${staged.password}; rc=$?; rm -f ${staged.password}; (exit $rc); }`] : [],
+      // Trees an earlier start marked complete hold what a person or a harness
+      // changed since, so a seed missing only its stub or env builds those alone.
+      `if ! { ${seeded}; }; then { docker image inspect ${image} >/dev/null 2>&1 || docker pull ${image} >/dev/null; } && { [ -f ${trees}/${IMAGE_TREES_COMPLETE_MARKER} ] || { ${seedTrees}; }; } && ${seedStub}; fi`,
+      `{ ${labelledWithImage("image", STUB_IMAGE)} || docker load -i ${trees}/${STUB_IMAGE_ARCHIVE} >/dev/null; }`,
+      `sudo find "$(pwd)/${PERSISTENT_ROOT}" -mindepth 1 -maxdepth 1 -name 'image-*' ! -path ${trees} -exec rm -rf {} +`
+    ];
+    const start = `mv -f ${staged.env} ${RUNTIME_ENV_PATH} && up=; for attempt in $(seq ${CONTAINER_CREATE_ATTEMPTS}); do [ "$attempt" = 1 ] || sleep 1; if ${labelledWithImage("container", containerName)}; then failure=$(docker start ${containerName} 2>&1 >/dev/null) && { up=1; break; }; else docker rm -f ${containerName} >/dev/null 2>&1; failure=$(${run} 2>&1 >/dev/null) && { up=1; break; }; fi; case "$failure" in *${shell(DOCKER_NAME_IN_USE)}*) ;; *) break ;; esac; done; [ -n "$up" ] || { echo "$failure" >&2; false; } && ${removeImage}`;
+    return {
+      prepare: holdingBootLock(IMAGE_PREPARATION_TIMEOUT_SECONDS, prepare.join(" && ")),
+      start: holdingBootLock(CONTAINER_START_TIMEOUT_SECONDS, start)
+    };
+  }
+  function healthProbe(port, windowSeconds) {
+    const booting = [...BOOTING_CONTAINER_STATES].join("|");
+    return `end=$(($(date +%s) + ${windowSeconds})); while :; do code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:${port}/global/health); [ "$code" = 200 ] && break; state=$(docker inspect --format '{{.State.Status}}' ${shell(containerName)} 2>/dev/null || echo missing); case "$state" in ${booting}) ;; *) break ;; esac; [ "$(date +%s)" -lt "$end" ] || break; sleep ${healthIntervalMs / 1e3}; done; echo "$code"; echo "$state"`;
+  }
+  async function waitForHealth(sandboxId, input, secrets) {
+    const port = runtimePort(input);
+    const until = Date.now() + healthTimeoutMs;
+    let last = "workspace runtime not ready";
+    while (Date.now() < until) {
+      const windowSeconds = Math.max(1, Math.min(HEALTH_PROBE_WINDOW_SECONDS, Math.ceil((until - Date.now()) / 1e3)));
+      const probe = await client.command(sandboxId, {
+        command: healthProbe(port, windowSeconds),
+        timeoutSeconds: windowSeconds + HEALTH_PROBE_MARGIN_SECONDS
+      });
+      const [code, state] = probe.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+      if (code === "200") return;
+      last = `health probe returned ${code || "no response"}`;
+      if (state !== void 0 && !BOOTING_CONTAINER_STATES.has(state)) {
+        last = `the runtime container is ${state}`;
+        break;
+      }
+    }
+    let diagnostic;
+    try {
+      const result = await client.command(sandboxId, {
+        command: `docker inspect --format 'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' ${shell(containerName)}; docker logs --tail 20 ${shell(containerName)} 2>&1`,
+        timeoutSeconds: 10
+      });
+      diagnostic = runtimeBootDiagnostic(scrubbed(`${result.stdout}
+${result.stderr}`, secrets), STDERR_TAIL_CHARS);
+    } catch {
+      diagnostic = "container diagnostics unavailable";
+    }
+    throw new SandboxRuntimeBootError(`Boat ${sandboxId} runtime did not become healthy: ${last}; ${diagnostic}`);
+  }
+  async function startContainer(sandboxId, input, hostId) {
+    const env = { ...bootEnv(input, hostId), ...await options.env?.(input, { id: hostId }) };
+    const boot2 = crypto.randomUUID();
+    const staged = {
+      env: `${RUNTIME_ENV_PATH}.${boot2}`,
+      ...options.registryAuth ? { password: `${REGISTRY_PASSWORD_PATH}.${boot2}` } : {}
+    };
+    const scripts = containerScripts(input, staged);
+    await client.writeFile(sandboxId, { path: staged.env, content: envFile(env) });
+    if (options.registryAuth && staged.password) {
+      await client.writeFile(sandboxId, { path: staged.password, content: options.registryAuth.password });
+    }
+    const secrets = [...workspaceRuntimeBootSecrets(env), ...options.registryAuth ? [options.registryAuth.password] : []];
+    let failure;
+    try {
+      await execOrThrow(sandboxId, scripts.prepare, "runtime image preparation", { timeoutSeconds: IMAGE_PREPARATION_TIMEOUT_SECONDS, secrets });
+      try {
+        await execOrThrow(sandboxId, scripts.start, "container start", { timeoutSeconds: CONTAINER_START_TIMEOUT_SECONDS, secrets });
+      } catch (error) {
+        throw error instanceof BoatDriverError ? new SandboxRuntimeBootError(error.message) : error;
+      }
+    } catch (error) {
+      failure = error;
+    }
+    try {
+      if (options.registryAuth || failure !== void 0) {
+        await execOrThrow(sandboxId, `rm -f ${[staged.env, staged.password].filter(Boolean).join(" ")}`, "staged file cleanup", { secrets });
+      }
+    } catch (cleanupFailure) {
+      if (failure === void 0) throw cleanupFailure;
+      if (failure instanceof Error) failure.message = `${failure.message}; ${cleanupFailure instanceof Error ? cleanupFailure.message : String(cleanupFailure)}`;
+    }
+    if (failure !== void 0) throw failure;
+    return secrets;
+  }
+  async function boot(sandboxId, input, hostId) {
+    await input.onMachineReady?.();
+    const port = runtimePort(input);
+    const secrets = await startContainer(sandboxId, input, hostId);
+    await input.onImageReady?.();
+    await execOrThrow(sandboxId, holdingBootLock(HOST_PUBLISH_TIMEOUT_SECONDS, `host ${port} --public`), "host publish", {
+      timeoutSeconds: HOST_PUBLISH_TIMEOUT_SECONDS,
+      retryOnceOn: HOST_RELAY_NOT_STOPPED
+    });
+    await waitForHealth(sandboxId, input, secrets);
+    await client.update(sandboxId, { ttlSeconds: null });
+    const urlResult = await execOrThrow(sandboxId, `host url ${port} --public`, "host url");
+    const url = trimToUndefined(urlResult.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).pop());
+    if (!url?.startsWith("https://") || url.includes("?")) {
+      throw new BoatDriverError(`Boat ${sandboxId} did not return an ungated HTTPS URL for port ${port}`);
+    }
+    return {
+      workspaceId: input.workspaceId,
+      sandboxId,
+      url,
+      hostId,
+      driverResourceId: sandboxId,
+      driver: { id: "boat", resourceId: sandboxId },
+      labels: { ...input.labels, ...resolveImage(input) === options.image ? { [SANDBOX_IMAGE_LABEL]: options.image } : {} }
+    };
+  }
+  function assertNetwork(input) {
+    if (input.net && input.net.mode !== "allow-all") {
+      throw new BoatDriverError("Boat SandboxDriver cannot enforce host-based network policy");
+    }
+  }
+  async function createSandbox(input) {
+    const create = (from) => client.create({
+      idempotencyKey: `claxedo:${input.workspaceId}:${input.epoch}${from ? ":template" : ""}`,
+      ttlSeconds: BOOT_TTL_SECONDS,
+      ...input.machineClass ? { type: input.machineClass } : {},
+      ...from ? { from } : {}
+    });
+    const template = options.runtimeTemplate;
+    if (!template || template.image !== resolveImage(input)) return create();
+    try {
+      return await create(template.shareCode);
+    } catch (err) {
+      if (!(err instanceof BoatApiError && TEMPLATE_UNREADABLE_CODES.has(err.code))) throw err;
+      console.warn(`Boat runtime template for ${template.image} is unreadable with this key (${err.code}); the sandbox pulls and seeds the image instead`);
+      return create();
+    }
+  }
+  async function ensureHost(input) {
+    assertNetwork(input);
+    const hostId = input.hostId ?? `boat-${input.workspaceId}`;
+    const created = await createSandbox(input).catch((err) => {
+      if (isTransientDriverError(err, TRANSIENT_MARKERS)) return void 0;
+      throw err;
+    });
+    if (!created) return { provisioning: true, retryAfterMs: TRANSIENT_DRIVER_RETRY_MS };
+    const resource = { sandboxId: created.id, hostId, driverResourceId: created.id, labels: input.labels };
+    const failures = [];
+    try {
+      await input.onResource?.(resource);
+    } catch (handoffError) {
+      failures.push(handoffError);
+      try {
+        await destroy({ ...resource, workspaceId: input.workspaceId });
+      } catch (deleteError) {
+        failures.push(deleteError);
+      }
+    }
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) throw new AggregateError(failures, `Boat ${created.id} resource handoff and deletion failed`);
+    const ready = await waitUntilReady(created.id);
+    if (!ready) return { provisioning: true, retryAfterMs: 0 };
+    return boot(created.id, input, hostId);
+  }
+  async function resumeHost(input) {
+    const sandboxId = input.lease.sandboxId;
+    if (!sandboxId) throw new BoatDriverError("Cannot resume Boat without its sandbox id");
+    assertNetwork(input.ensure);
+    const hostId = input.ensure.hostId ?? input.lease.hostId ?? `boat-${input.ensure.workspaceId}`;
+    const state = await stateAfterArchiving(sandboxId);
+    if (state === void 0) return { provisioning: true, retryAfterMs: 0 };
+    if (state === "archived") {
+      await client.resume(sandboxId, {
+        ttlSeconds: BOOT_TTL_SECONDS,
+        ...input.ensure.machineClass ? { type: input.ensure.machineClass } : {}
+      }).catch((err) => {
+        if (err instanceof BoatApiError && err.code === RESUME_UNDER_WAY) return;
+        hostGoneOrThrow(err);
+      });
+    }
+    const ready = await waitUntilReady(sandboxId);
+    if (!ready) return { provisioning: true, retryAfterMs: 0 };
+    return boot(sandboxId, input.ensure, hostId);
+  }
+  async function stop(target) {
+    await client.command(target.sandboxId, {
+      command: `docker stop -t ${CONTAINER_STOP_GRACE_SECONDS} ${containerName} >/dev/null 2>&1; true`,
+      timeoutSeconds: CONTAINER_STOP_GRACE_SECONDS + 30
+    }).then(() => void 0, notRunningOrThrow);
+    await client.stop(target.sandboxId).catch(archivedOrThrow);
+  }
+  async function destroy(target) {
+    await client.delete(target.sandboxId);
+  }
+  async function inspect(target) {
+    try {
+      const { state } = await client.get(target.sandboxId);
+      return READY_STATES.has(state) || PENDING_STATES.has(state) ? "serving" : "stopped";
+    } catch (err) {
+      if (err instanceof BoatApiError && GONE_CODES.has(err.code)) return "gone";
+      throw err;
+    }
+  }
+  return {
+    id: "boat",
+    metadata: sandboxDriverCatalog.boat.metadata,
+    image: options.image,
+    ensureHost,
+    resumeHost,
+    async touch() {
+    },
+    suspend: stop,
+    stop,
+    destroy,
+    inspect
+  };
+}
+
+// src/drivers/boat-named-snapshots.ts
+var STATUSES = ["saving", "ready", "failed"];
+function namedSnapshot(value) {
+  const snapshot = asRecord(value) ?? invalid();
+  const status = STATUSES.find((known) => known === snapshot.status) ?? invalid();
+  return { name: requiredText(snapshot.name), status, createdAt: requiredText(snapshot.createdAt) };
+}
+function share(value) {
+  const entry = asRecord(value) ?? invalid();
+  const status = requiredText(entry.status);
+  if (status !== "active" && status !== "revoked") invalid();
+  return { id: requiredText(entry.id), status, createdAt: requiredText(entry.createdAt) };
+}
+function list(value, item) {
+  return Array.isArray(value) ? value.map(item) : invalid();
+}
+function createBoatNamedSnapshotClient(options) {
+  const api = createBoatApi(options);
+  const path = (name) => `/named-snapshots/${encodeURIComponent(name)}`;
+  return {
+    /** A stopped sandbox is saved from its last snapshot; the save settles in the background. */
+    async save(input) {
+      return namedSnapshot((await api("/named-snapshots", ["snapshot.named.saving"], { method: "POST", body: input })).snapshot);
+    },
+    async get(name) {
+      try {
+        return namedSnapshot((await api(path(name), ["snapshot.named.info"])).snapshot);
+      } catch (err) {
+        if (err instanceof BoatApiError && err.status === 404) return void 0;
+        throw err;
+      }
+    },
+    /** Newest first. */
+    async list() {
+      return list((await api("/named-snapshots", ["snapshot.named.list"])).snapshots, namedSnapshot);
+    },
+    async delete(name) {
+      await api(path(name), ["snapshot.named.deleted"], { method: "DELETE" });
+    },
+    /** Boat shows the code only in this answer and keeps a hash of it. */
+    async share(name) {
+      const body = await api(`${path(name)}/shares`, ["snapshot.share.created"], { method: "POST" });
+      return { shareCode: requiredText(body.shareCode), share: share(body.share) };
+    },
+    async shares(name) {
+      return list((await api(`${path(name)}/shares`, ["snapshot.share.list"])).shares, share);
+    },
+    async revokeShare(name, shareId) {
+      await api(`${path(name)}/shares/${encodeURIComponent(shareId)}`, ["snapshot.share.revoked"], { method: "DELETE" });
+    }
+  };
+}
+
+// src/drivers/boat-template.ts
+var DEFAULT_PREFIX = "claxedo-rt-";
+var DEFAULT_KEEP = 3;
+var NAME_HASH_CHARS = 12;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_HYDRATION_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_STOP_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_SAVE_TIMEOUT_MS = 10 * 6e4;
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function boatRuntimeTemplateName(image, prefix = DEFAULT_PREFIX) {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(image)));
+  const name = `${prefix}${Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, NAME_HASH_CHARS)}`;
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(name)) throw new Error(`Boat refuses the named snapshot name ${name}`);
+  return name;
+}
+function clients(options) {
+  const connection = {
+    apiKey: options.apiKey,
+    ...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+    ...options.timeoutMs ? { timeoutMs: options.timeoutMs } : {},
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  };
+  return { connection, sandboxes: createBoatClient(connection), snapshots: createBoatNamedSnapshotClient(connection) };
+}
+async function pollBoat(label, timeoutMs, intervalMs, read) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const value = await read();
+    if (value !== void 0) return value;
+    if (Date.now() >= deadline) throw new Error(`${label} did not happen within ${Math.round(timeoutMs / 1e3)} s`);
+    await sleep2(intervalMs);
+  }
+}
+async function ensureBoatRuntimeTemplate(options) {
+  const { snapshots } = clients(options);
+  const name = await boatRuntimeTemplateName(options.image, options.prefix);
+  const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const existing = await pollBoat(`Boat template ${name} settling`, options.saveTimeoutMs ?? DEFAULT_SAVE_TIMEOUT_MS, interval, async () => {
+    const snapshot = await snapshots.get(name);
+    return snapshot?.status === "saving" ? void 0 : snapshot ?? null;
+  });
+  if (existing?.status === "ready") {
+    options.log?.(`template ${name} for ${options.image} exists`);
+    return { name, built: false };
+  }
+  await buildTemplate(options, name);
+  return { name, built: true };
+}
+async function buildTemplate(options, name) {
+  const { connection, sandboxes, snapshots } = clients(options);
+  const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const log = options.log ?? (() => {
+  });
+  const started = Date.now();
+  const elapsed = () => `${((Date.now() - started) / 1e3).toFixed(1)} s`;
+  const driver = createBoatSandboxDriver({
+    ...connection,
+    image: options.image,
+    controlEnv: { relayVerifyPem: generateKeyPairSync("ed25519").publicKey.export({ type: "spki", format: "pem" }).toString() },
+    ...options.driver
+  });
+  const workspaceId = `${name}-${started.toString(36)}`;
+  let sandboxId;
+  const ensure = (epoch) => ({
+    workspaceId,
+    homeRegion: "auto",
+    epoch,
+    labels: {},
+    source: { kind: "empty" },
+    onResource: async (resource) => {
+      sandboxId = resource.sandboxId;
+    }
+  });
+  const boot = async (epoch) => {
+    for (; ; ) {
+      const lease = sandboxLease({ workspaceId, homeRegion: "auto", driver: "boat", epoch, sandboxId });
+      const result = sandboxId ? await driver.resumeHost({ lease, ensure: ensure(epoch) }) : await driver.ensureHost(ensure(epoch));
+      if (!("provisioning" in result)) return result;
+      await sleep2(result.retryAfterMs);
+    }
+  };
+  const archived = (id) => pollBoat(`Boat ${id} stop`, options.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS, interval, async () => (await sandboxes.get(id)).state === "archived" ? true : void 0);
+  try {
+    log(`building template ${name} for ${options.image}`);
+    const target = await boot(1);
+    log(`builder ${target.sandboxId} seeded and healthy at ${elapsed()}`);
+    await driver.stop(target);
+    await archived(target.sandboxId);
+    log(`builder stopped at ${elapsed()}`);
+    await boot(2);
+    log(`builder woke at ${elapsed()}`);
+    await pollBoat(`Boat ${target.sandboxId} hydration`, options.hydrationTimeoutMs ?? DEFAULT_HYDRATION_TIMEOUT_MS, interval, async () => (await sandboxes.get(target.sandboxId)).hydrated ? true : void 0);
+    log(`builder hydrated at ${elapsed()}`);
+    const reset = await sandboxes.command(target.sandboxId, { command: boatTemplateResetCommand(), timeoutSeconds: 120 });
+    if (reset.exitCode !== 0) throw new Error(`Boat ${target.sandboxId} template reset failed (exit ${reset.exitCode ?? "signal"})`);
+    await sandboxes.stop(target.sandboxId);
+    await archived(target.sandboxId);
+    log(`builder reset and stopped at ${elapsed()}`);
+    await snapshots.save({ sandboxId: target.sandboxId, name });
+    const saved = await pollBoat(`Boat template ${name} save`, options.saveTimeoutMs ?? DEFAULT_SAVE_TIMEOUT_MS, interval, async () => {
+      const snapshot = await snapshots.get(name);
+      return snapshot?.status === "saving" ? void 0 : snapshot ?? null;
+    });
+    if (saved?.status !== "ready") throw new Error(`Boat template ${name} save ${saved ? "failed" : "vanished"}`);
+    log(`template ${name} saved at ${elapsed()}`);
+  } finally {
+    if (sandboxId) await sandboxes.delete(sandboxId);
+  }
+}
+async function shareBoatRuntimeTemplate(options) {
+  const { snapshots } = clients(options);
+  const created = await snapshots.share(await boatRuntimeTemplateName(options.image, options.prefix));
+  return { template: { image: options.image, shareCode: created.shareCode }, shareId: created.share.id };
+}
+async function revokeBoatRuntimeTemplateShares(options, deployedShareId) {
+  const { snapshots } = clients(options);
+  const name = await boatRuntimeTemplateName(options.image, options.prefix);
+  const shares = (await snapshots.shares(name)).filter((share2) => share2.status === "active");
+  if (!shares.some((share2) => share2.id === deployedShareId)) throw new Error(`Boat template ${name} has no active share ${deployedShareId}`);
+  const revoked = shares.filter((share2) => share2.id !== deployedShareId).map((share2) => share2.id);
+  for (const id of revoked) await snapshots.revokeShare(name, id);
+  return revoked;
+}
+async function pruneBoatRuntimeTemplates(options) {
+  const { snapshots } = clients(options);
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  const current = await boatRuntimeTemplateName(options.image, prefix);
+  const others = (await snapshots.list()).filter((snapshot) => snapshot.name.startsWith(prefix) && snapshot.name !== current && snapshot.status !== "saving").sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+  const removed = others.slice(Math.max(0, (options.keep ?? DEFAULT_KEEP) - 1)).map((snapshot) => snapshot.name);
+  for (const name of removed) await snapshots.delete(name);
+  if (removed.length) options.log?.(`pruned templates ${removed.join(", ")}`);
+  return removed;
+}
+export {
+  boatRuntimeTemplateName,
+  ensureBoatRuntimeTemplate,
+  pruneBoatRuntimeTemplates,
+  revokeBoatRuntimeTemplateShares,
+  shareBoatRuntimeTemplate
+};