@claxedo/sandbox-manager 0.10.1 → 0.10.2

package/README.md

@@ -108,7 +108,13 @@ nothing. Without a template, or when the organization's key cannot read it, or
 for any other image, the first start seeds them. The seed runs once per image, at the start that first names it: it pulls the
 image, streams the trees out of a created container of it with `docker cp` and
 unpacks them as root, leaving out `~/.cache` (which Boat's own snapshots leave
-out too) and npm's cache. The persistent root is created as root too: Docker
+out too) and npm's cache. Boat's link to ghcr resets mid-pull (2 of 8 staging
+updates on 2026-10-22, `failed to copy: … connection reset by peer`), and
+Docker ends a pull at the first reset, keeping the layers it finished and none
+of the ones in flight. So the pull runs again after a transport failure
+(connection reset, unexpected EOF, a timeout) for as long as each run finishes
+a layer no run before it did; any other failure, and a run that finished
+nothing new, fails the boot with the pull's own output. The persistent root is created as root too: Docker
 made it as root on every sandbox that booted before the trees existed, and the
 VM user cannot create inside it. The seed then saves beside the trees what the
 container needs besides them: the image's env (`image.env`, given to the
@@ -152,9 +158,35 @@ the container leaves `running`/`paused`. A sandbox still archiving from a stop,
 which Boat offers no wait for, is read again after 250 ms, doubling to 2 s.
 
 A wake that pulled (before the stub) took 57–77 s, and failed when ghcr reset
-the connection. An image update re-seeds:
-the new image is pulled and seeded as above, its stub replaces the old one, and
-the old image's trees are removed.
+the connection. A wake whose machine holds only an older image keeps serving
+that image: its trees, stub and env are there, and the runtime in them is no
+older than `MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION`. The wake answers
+with that image's label, so the workspace reads as outdated, instead of waiting
+60–100 s on the new image's pull and seed (staging, 2026-10-21). The update
+runs only when a start asks for it with `updateImage` (a person's Restart to
+update): the new image is pulled and seeded as above, its stub replaces the
+old one, and the old image's trees are removed. That step is a start of its
+own on the serving lease's epoch, whose phases are timed from the update. An
+update whose step fails leaves the lease serving its image and answers the
+start with the driver's reason, which the manager logs, and a start asking for
+the update of a workspace already serving the deployment's image answers it as
+it is. A cold start, and a wake whose older runtime is
+below the floor, takes the new image at once. On staging (2026-10-22, 0.10.1
+to 0.10.2) the wake that kept the image answered in 22 s and the update's step
+ran 92.7 s.
+
+`MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION` (`src/runtime-version.ts`) is the one
+floor for every driver: the oldest runtime this control plane and relay serve,
+whether a Cloudflare restore brings it back or a Boat wake keeps it. Below it a
+workspace updates and keeps its files on every driver: a Boat wake takes the
+new image over the same `/workspace` and homes, and a Cloudflare restore
+carries the repository and HOME into the current image. A runtime
+security fix, or a control-plane or relay contract an older runtime cannot
+speak, raises the floor and the workspace-runtime version together, in the
+commit that makes the change; a test keeps the floor at or below the runtime
+version the tree builds. Each connection names the image it serves
+(`runtimeImage`), and every mint of an outdated one is the
+`sandbox.runtime_outdated_served` event.
 
 A start runs as two commands: the preparation (daemon, login, seed, stub)
 changes nothing a running container serves from, so its failure leaves a

package/dist/checkpoint-manager.mjs

@@ -53,11 +53,19 @@ var PUBLIC_API_ERRORS = {
   enrollment_paused: { status: 403, message: "enrollment_paused" },
   enrollment_owner_ineligible: { status: 403, message: "enrollment_owner_ineligible" },
   enrollment_key_version_mismatch: { status: 403, message: "enrollment_key_version_mismatch" },
+  enrollment_denied: { status: 403, message: "enrollment_denied" },
+  enrollment_approval_expired: { status: 403, message: "enrollment_approval_expired" },
+  enrollment_awaiting_approval: { status: 403, message: "enrollment_awaiting_approval" },
   invitation_invalid: { status: 403, message: "invitation_invalid" },
   invitation_expired: { status: 410, message: "invitation_expired" },
   invitation_revoked: { status: 410, message: "invitation_revoked" },
   invitation_redeemed: { status: 409, message: "invitation_redeemed" },
   invitation_host_conflict: { status: 409, message: "invitation_host_conflict" },
+  pairing_invalid: { status: 403, message: "pairing_invalid" },
+  pairing_expired: { status: 410, message: "pairing_expired" },
+  pairing_used: { status: 409, message: "pairing_used" },
+  pairing_owner_signed_out: { status: 410, message: "pairing_owner_signed_out" },
+  pairing_decided: { status: 409, message: "pairing_decided" },
   enrollment_generation_superseded: { status: 409, message: "enrollment_generation_superseded" },
   host_assignment_outside_scope: { status: 400, message: "host_assignment_outside_scope" },
   host_sealing_key_undeclared: { status: 409, message: "host_sealing_key_undeclared" },

package/dist/contract.d.ts

@@ -337,6 +337,13 @@ export type SandboxDriverEnsureInput = {
     net?: SandboxNetworkPolicy;
     /** Optional snapshot/image to boot from (user-supplied or pre-built). */
     snapshot?: string;
+    /**
+     * The person asked for the deployment's image. Without it, a resume of a
+     * machine that holds only an older image may keep serving that one and
+     * report it, so the workspace reads as outdated instead of waiting on the
+     * new image's preparation.
+     */
+    updateImage?: true;
 };
 export type SandboxTarget = {
     workspaceId?: string;
@@ -503,6 +510,8 @@ export type SandboxManagerInput = {
      */
     net?: SandboxNetworkPolicy;
     snapshot?: string;
+    /** @see SandboxDriverEnsureInput.updateImage */
+    updateImage?: true;
     /**
      * Called by the one ensure whose acquire created the workspace's first
      * lease, before its driver is asked for anything; a concurrent start that
@@ -551,6 +560,8 @@ export type SandboxEnsureResult = ({
      * delivered — the provider edge still holds the previous set.
      */
     stale?: true;
+    /** @see SandboxTargetResult */
+    imageOutdated?: true;
 }) | {
     status: "provisioning";
     retryAfterMs: number;
@@ -572,7 +583,7 @@ export type SandboxTargetResult = ({
     epoch: number;
     routingId?: string;
     homeRegion: SandboxRegion;
-    /** The runtime booted from an image other than the driver's current one; its next ensure boots the current one. */
+    /** The runtime booted from an image other than the driver's current one; an ensure asked to `updateImage` boots the current one. */
     imageOutdated?: true;
     /** The start that brought this epoch up, as observed; the run still delivering its settings is timed from it. */
     start?: SandboxEpochStart;

package/dist/driver-ensure-input.d.ts

@@ -0,0 +1,21 @@
+import type { SandboxDriver, SandboxDriverEnsureInput, SandboxLease, SandboxManagerInput, SandboxRegion } from "./contract";
+export declare function leaseHostId(driver: SandboxDriver, workspaceId: string, lease: SandboxLease, managerInput: SandboxManagerInput | undefined): string;
+/**
+ * Build the driver-facing ensure input.
+ *
+ * This is the ONLY place a `SandboxDriverEnsureInput` is constructed, which is
+ * what makes the egress guarantee structural rather than a promise kept by each
+ * call site: `net` is copied across only when `sandboxEgressDisposition` says
+ * the driver can enforce it. A driver declaring `egressControl: "none"` — every
+ * driver that throws on a restricted policy, plus the two that silently drop it
+ * — cannot be reached by one through any path.
+ */
+export declare function ensureHostInput(input: {
+    driver: SandboxDriver;
+    workspaceId: string;
+    lease: SandboxLease;
+    homeRegion: SandboxRegion;
+    managerInput?: SandboxManagerInput;
+    leaseEnv?: Record<string, string>;
+    appLabel: string;
+}): SandboxDriverEnsureInput;

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

@@ -0,0 +1,90 @@
+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 (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 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, 2026-10-21); 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 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.
+ */
+/**
+ * `docker pull` that goes on after the connection under it breaks. Docker ends
+ * a pull at the first reset and keeps none of a layer that was still
+ * downloading, but keeps every layer it finished, so pulling again continues
+ * from those. Boat's link to ghcr resets mid-pull (2 of 8 staging updates on
+ * 22 October, `failed to copy: read tcp …: connection reset by peer`). A pull
+ * is run again only after such a transport failure and only while each run
+ * finishes a layer none before it did, so it ends; any other failure, and a
+ * run that finished nothing new, fails with the pull's own output.
+ */
+/** 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:";
+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

@@ -81,6 +81,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) {
@@ -181,6 +188,13 @@ 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;
+
 // src/image-name.ts
 function assertSandboxImageReference(image) {
   if (!image || image !== image.trim() || image.startsWith("-") || /\s/.test(image)) {
@@ -592,21 +606,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,6 +635,92 @@ 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";
+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 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 VERSION_FILE = "opt/workspace-runtime/workspace-runtime-version";
+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() { version=$(cat "$1/${VERSION_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} ]; }`
+].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")/${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;
@@ -643,16 +732,6 @@ 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;
@@ -665,10 +744,6 @@ 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));
 }
@@ -678,12 +753,6 @@ function scrubbed(text, secrets) {
 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);
@@ -764,43 +833,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"`;
@@ -836,22 +868,41 @@ ${result.stderr}`, secrets), STDERR_TAIL_CHARS);
     }
     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 +913,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 +945,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 +994,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 +1014,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

@@ -49,16 +49,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;