@claxedo/sandbox-manager 0.10.1 → 0.10.3

package/dist/drivers/boat-client.d.ts

@@ -18,7 +18,7 @@ export type BoatFetch = (input: string, init?: RequestInit) => Promise<Response>
 /**
  * What Boat's 429 `rate_limited` says about the account's start limit: the
  * window that is used up, its limit, and the starts used of each window. It
- * names no time the window reopens (2026-10-15), so none is kept.
+ * names no time the window reopens, so none is kept.
  */
 export type BoatStartLimit = {
     window: SandboxStartWindow;
@@ -33,10 +33,10 @@ export declare class BoatApiError extends Error {
     readonly status?: number | undefined;
     /** Boat answers 401 or 403 to the API key itself, never to a sandbox it was asked about. */
     readonly providerKeyRefused: boolean;
-    /** Create, fork and resume each count as one start (Boat's own refusal, 2026-10-15). */
+    /** Create, fork and resume each count as one start (Boat's own refusal). */
     readonly providerRateLimited?: SandboxStartLimit;
     readonly startLimit?: BoatStartLimit;
-    /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed` (2026-10-17). */
+    /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed`. */
     readonly sandboxState?: BoatSandboxState;
     constructor(message: string, code: string, status?: number | undefined, refusal?: {
         startLimit?: BoatStartLimit;
@@ -75,7 +75,7 @@ export declare function createBoatClient(options: BoatClientOptions): {
     }): Promise<void>;
     /**
      * `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).
+     * Boat's reference example answers `sandbox.info`; the API answers `sandbox.updated`.
      */
     update(id: string, input: {
         ttlSeconds: number | null;

package/dist/drivers/boat-machine.d.ts

@@ -0,0 +1,80 @@
+export declare const IMAGE_PREPARATION_TIMEOUT_SECONDS = 600;
+export declare const CONTAINER_START_TIMEOUT_SECONDS = 120;
+export declare const DEFAULT_CONTAINER_NAME = "claxedo-runtime";
+export declare const RUNTIME_ENV_PATH = ".claxedo-runtime-env";
+export declare const REGISTRY_PASSWORD_PATH = ".claxedo-registry-password";
+/**
+ * Turns a booted machine into one any workspace can start from: it keeps what
+ * every machine of the image shares (the image's trees, stub archive and env,
+ * and Boat's ~/.ascii/playbook.json) and removes what this machine's boot made
+ * (the runtime container and Boat's record and image archive of it, the
+ * workspace, the runtime's state, the boot's env). Nothing the runtime wrote
+ * into the image's trees was found there (the trees held only the image's own
+ * entries after two boots); what else differs on the machine
+ * is Boat's own, and a machine created from the template gets its own
+ * machine-id, SSH host keys, hostname and no hosted port.
+ */
+export declare function boatTemplateResetCommand(): string;
+export type StagedFiles = {
+    env: string;
+    password?: string;
+};
+export declare function holdingBootLock(commandTimeoutSeconds: number, script: string): string;
+/**
+ * The image a boot names and the one it may keep serving instead. A resume of
+ * a machine whose trees hold only an older image keeps that image when its
+ * runtime is no older than the oldest the control plane serves, so a wake
+ * after a deploy does not wait 60–100 s on the new image's pull and seed
+ * (staging); the workspace then reads as outdated, and the
+ * person's Restart to update asks for the new image with `keepPreviousImage`
+ * off. A cold boot has no previous image to keep.
+ */
+export type MachineBoot = {
+    image: string;
+    keepPreviousImage: boolean;
+    workspaceId: string;
+    directory: string;
+    port: number;
+    runtimeCommand: string;
+    containerName: string;
+    registry?: {
+        server: string;
+        username: string;
+    };
+    staged: StagedFiles;
+    staleStagedMinutes: number;
+};
+/** Where a boot's preparation leaves the image it booted for its container start to read. */
+export declare function bootedImageFile(staged: StagedFiles): string;
+/** The image a preparation booted: the last line it prints, since `docker login` prints before it. */
+export declare function bootedImage(prepareStdout: string): string | undefined;
+/** The last line a preparation prints when its pull gave up on a registry link that kept breaking. */
+export declare const IMAGE_DOWNLOAD_INTERRUPTED = "image_download_interrupted";
+/** Leads the line a boot that could keep the machine's last image prints when it takes the named one instead, with what it found. */
+export declare const KEPT_IMAGE_SKIPPED = "kept_image_skipped:";
+/**
+ * The command carries only paths: env arrives through the staged file
+ * (mounted read-only, sourced by the entrypoint at every container start so
+ * multi-line values like PEMs survive — `docker run --env-file` cannot
+ * express them), and the registry password is piped to `docker login` from a
+ * file that is removed whatever the outcome; a failed login aborts the chain.
+ *
+ * Two commands. `prepare` changes nothing a running container serves from:
+ * it waits for the daemon (a resume reboots the VM, and Docker comes up as a
+ * systemd service after Boat reports the sandbox ready), logs in, and settles
+ * which image boots: the one named when its trees, stub and env are there;
+ * the one the machine last booted when the boot may keep it and its trees
+ * hold a runtime still served; otherwise the one named, pulled and seeded
+ * where anything is missing. It loads that image's stub when Docker does not
+ * hold it, removes every other image's trees, writes the image for `start`
+ * and prints it. A failure there leaves a runtime of the previous image
+ * serving. `start` then replaces another image's container with one of the
+ * booted image, or starts that image's container that is already there: the
+ * one the stop kept, which Boat's restore creates again stopped, or one Boat
+ * recreated after a stop that was not this driver's; then it removes the
+ * image if a seed left it. A failure there leaves nothing serving.
+ */
+export declare function machineBootScripts(boot: MachineBoot): {
+    prepare: string;
+    start: string;
+};

package/dist/drivers/boat-preparation.test-support.d.ts

@@ -0,0 +1,2 @@
+/** What a Boat machine's preparation prints when the image its command names boots: that image, as the real script's last line. */
+export declare function preparedImageOutput(command: string): string;

package/dist/drivers/boat-template.mjs

@@ -63,6 +63,7 @@ var sandboxDriverCredentialFields = {
     { key: "worker_url", label: "Worker URL" }
   ],
   boat: [{ key: "api_key", label: "API Key", secret: true }],
+  agent37: [{ key: "api_key", label: "API Key", secret: true }],
   docker: [{ key: "image", label: "Image" }]
 };
 var sandboxDriverLabels = {
@@ -70,6 +71,7 @@ var sandboxDriverLabels = {
   vercel: "Vercel",
   cloudflare: "Cloudflare",
   boat: "Boat",
+  agent37: "Agent37",
   docker: "Docker"
 };
 
@@ -81,6 +83,13 @@ var SandboxRuntimeBootError = class extends Error {
     this.name = "SandboxRuntimeBootError";
   }
 };
+var SandboxImageDownloadError = class extends Error {
+  imageDownloadFailed = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxImageDownloadError";
+  }
+};
 var SandboxHostGoneError = class extends Error {
   hostGone = true;
   constructor(reason) {
@@ -136,6 +145,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 = {
@@ -181,6 +194,17 @@ function envFile(input) {
   }).join("\n") + "\n";
 }
 
+// src/runtime-version.ts
+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} ]`;
+}
+
 // src/image-name.ts
 function assertSandboxImageReference(image) {
   if (!image || image !== image.trim() || image.startsWith("-") || /\s/.test(image)) {
@@ -200,6 +224,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;
@@ -285,8 +330,8 @@ var sandboxDriverCatalog = {
       hostWatchesIdle: true,
       targetAccess: "relay",
       secretBrokering: "native",
-      // Credential handlers do not restrict unrelated destinations.
-      egressControl: "none",
+      // The sandbox Worker starts the container without internet and routes each allowed host through itself; a Worker that cannot confirm that refuses the start.
+      egressControl: "hosts",
       // 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",
@@ -324,6 +369,33 @@ var sandboxDriverCatalog = {
       machineClasses: ["small", "default", "large"]
     }
   },
+  agent37: {
+    id: "agent37",
+    label: sandboxDriverLabels.agent37,
+    credentialFields: sandboxDriverCredentialFields.agent37,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
+    billing: agent37Billing,
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      // An instance's network policy lists domains, reached over HTTPS on 443 alone, and IPv4 ranges; private ranges stay blocked whatever it lists.
+      egressControl: "hosts-and-cidrs",
+      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,
@@ -396,10 +468,10 @@ var BoatApiError = class extends Error {
   }
   /** 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). */
+  /** Create, fork and resume each count as one start (Boat's own refusal). */
   providerRateLimited;
   startLimit;
-  /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed` (2026-10-17). */
+  /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed`. */
   sandboxState;
 };
 function startCount(value) {
@@ -527,7 +599,7 @@ function createBoatClient(options) {
     },
     /**
      * `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).
+     * Boat's reference example answers `sandbox.info`; the API answers `sandbox.updated`.
      */
     async update(id, input) {
       const value = sandbox(await api(path(id), ["sandbox.updated", "sandbox.info"], { method: "PATCH", body: input }));
@@ -592,21 +664,10 @@ function isTransientDriverError(err, markers) {
 }
 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"]);
+// src/drivers/boat-machine.ts
 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 DEFAULT_CONTAINER_NAME = "claxedo-runtime";
 var DOCKER_DAEMON_WAIT_SECONDS = 120;
 var RUNTIME_ENV_PATH = ".claxedo-runtime-env";
 var REGISTRY_PASSWORD_PATH = ".claxedo-registry-password";
@@ -632,17 +693,6 @@ 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`,
@@ -653,6 +703,91 @@ function boatTemplateResetCommand() {
   ];
   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 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 containerHostname(workspaceId) {
+  return workspaceId.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").slice(0, 63) || "claxedo";
+}
+function bootedImageFile(staged) {
+  return `${staged.env}.image`;
+}
+function bootedImage(prepareStdout) {
+  return prepareStdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).pop();
+}
+var stubLabel = `docker image inspect --format '{{index .Config.Labels "${IMAGE_LABEL}"}}' ${STUB_IMAGE} 2>/dev/null`;
+var treesFunctions = [
+  `trees_of() { printf '%s/${PERSISTENT_ROOT}/image-%s' "$(pwd)" "$(printf %s "$1" | sed 's/[^A-Za-z0-9._-]/-/g')"; }`,
+  `seeded() { [ -f "$1/${IMAGE_TREES_COMPLETE_MARKER}" ] && [ -f "$1/${STUB_IMAGE_ARCHIVE}" ] && [ -f "$1/${IMAGE_ENV_FILE}" ]; }`,
+  `served() { ${servedRuntimeVersionTest(`"$1/${SANDBOX_IMAGE_RUNTIME_VERSION_FILE}"`)}; }`
+].join(" && ");
+var IMAGE_DOWNLOAD_INTERRUPTED = "image_download_interrupted";
+var KEPT_IMAGE_SKIPPED = "kept_image_skipped:";
+var PULL_RESUMING = `pull_resuming() { finished=$(mktemp) && while :; do if output=$(docker pull "$1" 2>&1); then rm -f "$finished"; return 0; fi; case "$output" in *"connection reset by peer"*|*"unexpected EOF"*|*"i/o timeout"*|*"TLS handshake timeout"*) ;; *) printf '%s\\n' "$output" >&2; rm -f "$finished"; return 1 ;; esac; before=$(wc -l < "$finished"); { cat "$finished"; printf '%s\\n' "$output" | sed -n -e 's/^\\([0-9a-f]\\{12\\}\\): Download complete$/\\1/p' -e 's/^\\([0-9a-f]\\{12\\}\\): Pull complete$/\\1/p'; } | sort -u > "$finished.next" && mv "$finished.next" "$finished"; [ "$(wc -l < "$finished")" -gt "$before" ] || { printf '%s\\n' "$output" ${IMAGE_DOWNLOAD_INTERRUPTED} >&2; rm -f "$finished"; return 1; }; done; }`;
+function machineBootScripts(boot) {
+  const named = shell(boot.image);
+  const trees = `"$(trees_of ${named})"`;
+  const bootedFile = bootedImageFile(boot.staged);
+  const containerOfBooted = `[ "$(docker container inspect --format '{{index .Config.Labels "${IMAGE_LABEL}"}}' ${boot.containerName} 2>/dev/null)" = "$booted" ]`;
+  const bootScript = [
+    `. ${CONTAINER_ENV_PATH}`,
+    `mkdir -p ${shell(boot.directory)}`,
+    `cd ${shell(boot.directory)}`,
+    `exec ${boot.runtimeCommand}`
+  ].join(" && ");
+  const mounts = [["workspace", boot.directory], ...PERSISTENT_HOME_MOUNTS];
+  const run = `docker run -d --name ${boot.containerName} --hostname ${shell(containerHostname(boot.workspaceId))} -p ${boot.port}:${boot.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} ${named} 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}}' ${named} > "$stub/${IMAGE_ENV_FILE}" && workdir=$(docker image inspect --format '{{or .Config.WorkingDir "/"}}' ${named}) && mkdir "$stub/root" ${ROOT_DIRECTORIES.map((directory) => `"$stub/root/${directory}"`).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}=${boot.image}`)} "$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 seedNamed = `{ docker image inspect ${named} >/dev/null 2>&1 || pull_resuming ${named}; } && { [ -f ${trees}/${IMAGE_TREES_COMPLETE_MARKER} ] || { ${seedTrees}; }; } && ${seedStub}`;
+  const keepPrevious = `previous=$(${stubLabel}) && [ -n "$previous" ] && seeded "$(trees_of "$previous")" && served "$(trees_of "$previous")"`;
+  const keptImageSkipped = `echo "${KEPT_IMAGE_SKIPPED} stub=\${previous:-none} seeded=$(seeded "$(trees_of "$previous")" && echo yes || echo no) version=$(cat "$(trees_of "$previous")/${SANDBOX_IMAGE_RUNTIME_VERSION_FILE}" 2>/dev/null || echo none)" >&2`;
+  const removeImage = `if docker image inspect "$booted" >/dev/null 2>&1; then leftovers=$(docker ps -aq --filter ancestor="$booted") && { [ -z "$leftovers" ] || docker rm -f $leftovers >/dev/null; } && id=$(docker image inspect --format '{{.Id}}' "$booted") && docker rmi "$booted" >/dev/null && sudo rm -f ${BOAT_SAVED_IMAGES}/"\${id#sha256:}".tar; fi`;
+  const prepare = [
+    `chmod 600 ${boot.staged.env}`,
+    `find . -maxdepth 1 \\( -name '${RUNTIME_ENV_PATH}.*' -o -name '${REGISTRY_PASSWORD_PATH}.*' \\) -mmin +${boot.staleStagedMinutes} -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} ]`,
+    ...boot.registry && boot.staged.password ? [`{ chmod 600 ${boot.staged.password}; docker login ${shell(boot.registry.server)} --username ${shell(boot.registry.username)} --password-stdin < ${boot.staged.password}; rc=$?; rm -f ${boot.staged.password}; (exit $rc); }`] : [],
+    treesFunctions,
+    PULL_RESUMING,
+    `booted=${named}`,
+    `if ! seeded ${trees}; then ` + (boot.keepPreviousImage ? `if ${keepPrevious}; then booted=$previous; else ${keptImageSkipped}; ${seedNamed}; fi` : seedNamed) + `; fi`,
+    `{ [ "$(${stubLabel})" = "$booted" ] || docker load -i "$(trees_of "$booted")/${STUB_IMAGE_ARCHIVE}" >/dev/null; }`,
+    `sudo find "$(pwd)/${PERSISTENT_ROOT}" -mindepth 1 -maxdepth 1 -name 'image-*' ! -path "$(trees_of "$booted")" -exec rm -rf {} +`,
+    `printf '%s\\n' "$booted" > ${bootedFile}`,
+    `printf '%s\\n' "$booted"`
+  ];
+  const start = `${treesFunctions} && booted=$(cat ${bootedFile}) && trees=$(trees_of "$booted") && rm -f ${bootedFile} && mv -f ${boot.staged.env} ${RUNTIME_ENV_PATH} && up=; for attempt in $(seq ${CONTAINER_CREATE_ATTEMPTS}); do [ "$attempt" = 1 ] || sleep 1; if ${containerOfBooted}; then failure=$(docker start ${boot.containerName} 2>&1 >/dev/null) && { up=1; break; }; else docker rm -f ${boot.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)
+  };
+}
+
+// src/drivers/boat.ts
+var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
+var DEFAULT_WORKSPACE_DIR = "/workspace";
+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 HOST_PUBLISH_TIMEOUT_SECONDS = 120;
+var BOOT_TTL_SECONDS = 30 * 60;
+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 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 hostGoneOrThrow(err) {
   if (err instanceof BoatApiError && GONE_CODES.has(err.code)) throw new SandboxHostGoneError(err.message);
   throw err;
@@ -665,24 +800,11 @@ 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";
+  return redactWorkspaceRuntimeBootSecrets(text, secrets).trim().slice(-STDERR_TAIL_CHARS);
 }
 var BoatDriverError = class extends Error {
   constructor(message) {
@@ -764,43 +886,6 @@ function createBoatSandboxDriver(options) {
       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"`;
@@ -829,29 +914,48 @@ function createBoatSandboxDriver(options) {
         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}
+      diagnostic = runtimeBootDiagnostic(redactWorkspaceRuntimeBootSecrets(`${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) {
+  async function startContainer(sandboxId, input, hostId, keepPreviousImage) {
     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);
+    const image = resolveImage(input);
+    const scripts = machineBootScripts({
+      image,
+      keepPreviousImage: keepPreviousImage && image === options.image,
+      workspaceId: input.workspaceId,
+      directory: workspaceDirectory(input),
+      port: runtimePort(input),
+      runtimeCommand,
+      containerName,
+      ...options.registryAuth ? { registry: { server: options.registryAuth.server, username: options.registryAuth.username } } : {},
+      staged,
+      staleStagedMinutes: BOOT_TTL_SECONDS / 60
+    });
     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;
+    let booted;
     try {
-      await execOrThrow(sandboxId, scripts.prepare, "runtime image preparation", { timeoutSeconds: IMAGE_PREPARATION_TIMEOUT_SECONDS, secrets });
+      const prepared = await execOrThrow(sandboxId, scripts.prepare, "runtime image preparation", { timeoutSeconds: IMAGE_PREPARATION_TIMEOUT_SECONDS, secrets }).catch((error) => {
+        throw error instanceof BoatDriverError && error.message.includes(IMAGE_DOWNLOAD_INTERRUPTED) ? new SandboxImageDownloadError(error.message) : error;
+      });
+      booted = bootedImage(prepared.stdout);
+      if (!booted) throw new BoatDriverError(`Boat ${sandboxId} runtime image preparation named no image it booted`);
+      const skipped = keepPreviousImage ? prepared.stderr.split("\n").find((line) => line.startsWith(KEPT_IMAGE_SKIPPED)) : void 0;
+      if (skipped) console.warn("A Boat wake took the deployment's image instead of the one the machine last booted", { sandboxId, workspaceId: input.workspaceId, found: skipped.slice(KEPT_IMAGE_SKIPPED.length).trim() });
       try {
         await execOrThrow(sandboxId, scripts.start, "container start", { timeoutSeconds: CONTAINER_START_TIMEOUT_SECONDS, secrets });
       } catch (error) {
@@ -862,19 +966,19 @@ ${result.stderr}`, secrets), STDERR_TAIL_CHARS);
     }
     try {
       if (options.registryAuth || failure !== void 0) {
-        await execOrThrow(sandboxId, `rm -f ${[staged.env, staged.password].filter(Boolean).join(" ")}`, "staged file cleanup", { secrets });
+        await execOrThrow(sandboxId, `rm -f ${[staged.env, staged.password, bootedImageFile(staged)].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;
+    if (failure !== void 0 || !booted) throw failure;
+    return { secrets, booted };
   }
-  async function boot(sandboxId, input, hostId) {
+  async function boot(sandboxId, input, hostId, keepPreviousImage) {
     await input.onMachineReady?.();
     const port = runtimePort(input);
-    const secrets = await startContainer(sandboxId, input, hostId);
+    const { secrets, booted } = await startContainer(sandboxId, input, hostId, keepPreviousImage);
     await input.onImageReady?.();
     await execOrThrow(sandboxId, holdingBootLock(HOST_PUBLISH_TIMEOUT_SECONDS, `host ${port} --public`), "host publish", {
       timeoutSeconds: HOST_PUBLISH_TIMEOUT_SECONDS,
@@ -894,7 +998,7 @@ ${result.stderr}`, secrets), STDERR_TAIL_CHARS);
       hostId,
       driverResourceId: sandboxId,
       driver: { id: "boat", resourceId: sandboxId },
-      labels: { ...input.labels, ...resolveImage(input) === options.image ? { [SANDBOX_IMAGE_LABEL]: options.image } : {} }
+      labels: { ...input.labels, ...resolveImage(input) === options.image ? { [SANDBOX_IMAGE_LABEL]: booted } : {} }
     };
   }
   function assertNetwork(input) {
@@ -943,7 +1047,7 @@ ${result.stderr}`, secrets), STDERR_TAIL_CHARS);
     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);
+    return boot(created.id, input, hostId, false);
   }
   async function resumeHost(input) {
     const sandboxId = input.lease.sandboxId;
@@ -963,7 +1067,7 @@ ${result.stderr}`, secrets), STDERR_TAIL_CHARS);
     }
     const ready = await waitUntilReady(sandboxId);
     if (!ready) return { provisioning: true, retryAfterMs: 0 };
-    return boot(sandboxId, input.ensure, hostId);
+    return boot(sandboxId, input.ensure, hostId, !input.ensure.updateImage);
   }
   async function stop(target) {
     await client.command(target.sandboxId, {

package/dist/drivers/boat.d.ts

@@ -22,12 +22,7 @@ export type BoatSandboxDriverOptions = {
     workspaceDir?: string;
     nativeHarness?: string;
     controlEnv?: WorkspaceRuntimeControlEnv;
-    /** Container name used for the runtime container inside the sandbox. */
     containerName?: string;
-    /**
-     * Optional `docker login` before the pull, for a private runtime registry.
-     * Omit for public images.
-     */
     registryAuth?: {
         server: string;
         username: string;
@@ -49,16 +44,4 @@ export type BoatSandboxDriverOptions = {
     operationTimeoutMs?: number;
     fetchImpl?: BoatFetch;
 };
-/**
- * Turns a booted machine into one any workspace can start from: it keeps what
- * every machine of the image shares (the image's trees, stub archive and env,
- * and Boat's ~/.ascii/playbook.json) and removes what this machine's boot made
- * (the runtime container and Boat's record and image archive of it, the
- * workspace, the runtime's state, the boot's env). Nothing the runtime wrote
- * into the image's trees was found there (Boat, 2026-10-16: the trees held only
- * the image's own entries after two boots); what else differs on the machine
- * is Boat's own, and a machine created from the template gets its own
- * machine-id, SSH host keys, hostname and no hosted port.
- */
-export declare function boatTemplateResetCommand(): string;
 export declare function createBoatSandboxDriver(options: BoatSandboxDriverOptions): SandboxDriver;