rightsize 0.7.8 → 0.7.10

package/dist/core/errors.js

@@ -158,6 +158,40 @@ export class ReuseFromCheckpointError extends Error {
         this.name = "ReuseFromCheckpointError";
     }
 }
+/**
+ * Thrown at `start()` when a container built via `GenericContainer.fromCheckpoint()`
+ * carries an env that no longer matches the checkpoint's own captured env —
+ * an extra `withEnv()` call, or one overriding a key the checkpoint already
+ * set — and the active backend has no way to apply that at restore time.
+ *
+ * msb is the one backend this affects: 0.7.1 replaced `run --from-snapshot`
+ * with a dedicated `msb restore` command that has no `-e`/`--env` flag at
+ * all (a disk-only restore replays the sandbox's own captured
+ * configuration). Before 0.7.1, an overridden or extended env silently
+ * reached the restored guest via `run -e`; since there is now no msb
+ * invocation this library could emit that would honor it, silently dropping
+ * it would let the workload boot with env the caller never asked for and
+ * without env it did ask for — a correctness bug, not a graceful
+ * degradation — so this throws instead, before any backend call. Restoring
+ * with the checkpoint's own env completely unchanged never hits this: only
+ * a call that actually changes what would be sent does. docker is
+ * unaffected — restoring there is an ordinary `docker create`/`run` against
+ * the committed image with a fresh env array, so this is never thrown when
+ * the active backend is `"docker"`.
+ */
+export class CheckpointRestoreEnvOverrideError extends Error {
+    backend;
+    constructor(
+    /** The active backend's name — always `"microsandbox"` today, the one backend this affects. */
+    backend) {
+        super(`fromCheckpoint(...).withEnv(...) cannot override or extend a checkpoint's captured env when restoring ` +
+            `on the '${backend}' backend — its restore command has no way to inject env at boot time, so an ` +
+            `overridden or extended env would be silently dropped instead of reaching the restored workload. ` +
+            `Restore with the checkpoint's own env unchanged, or bake the desired env into a fresh checkpoint instead.`);
+        this.backend = backend;
+        this.name = "CheckpointRestoreEnvOverrideError";
+    }
+}
 /**
  * Thrown by `copyFileToContainer`/`copyContentToContainer`/
  * `copyFileFromContainer` when `containerPath` is not absolute — both
@@ -326,4 +360,31 @@ export class TmpfsRootCheckpointError extends Error {
         this.name = "TmpfsRootCheckpointError";
     }
 }
+/**
+ * Thrown restoring a microsandbox checkpoint whose source container had no
+ * explicit command (the image's own default entrypoint was running) and
+ * whose registry entry carries no captured workload cmdline either —
+ * `msb restore` boots a restored sandbox with only its guest agent inside
+ * and never re-runs anything on its own (EMPIRICALLY VERIFIED against msb
+ * 0.7.1 — see `MsbCliBackend.bootRestoreOnce`'s own doc), so without EITHER
+ * source this library has no workload argv left to revive. Thrown instead of
+ * silently booting the sandbox idle — the checkpoint either predates
+ * workload-cmdline capture, or its capture attempt failed at checkpoint time
+ * (see `CheckpointRegistryEntry.capturedCommand`'s own doc on why a capture
+ * failure never fails the checkpoint that created it, only a later restore
+ * of it). Only ever thrown by the microsandbox backend.
+ */
+export class CheckpointWorkloadCommandMissingError extends Error {
+    ref;
+    constructor(
+    /** The checkpoint ref being restored. */
+    ref) {
+        super(`sandbox restore from checkpoint '${ref}' has no explicit command and no captured workload cmdline in ` +
+            "its registry entry — this checkpoint predates workload-cmdline capture, or its capture attempt " +
+            "failed at checkpoint time, so there is no workload argv left to revive. Re-checkpoint the source " +
+            "container under a build that captures one.");
+        this.ref = ref;
+        this.name = "CheckpointWorkloadCommandMissingError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/generic-container.d.ts

@@ -40,6 +40,15 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
     private requireIsolationRequested;
     private checkpointRef;
     private checkpointSourceBackend;
+    /**
+     * `cp.spec.env` exactly as captured, set once by `fromCheckpoint()` and
+     * never touched again — kept separate from the mutable `envPairs` so
+     * `start()` can tell "the caller re-applied the checkpoint's own env
+     * unchanged" from "the caller actually overrode or extended it" (see
+     * `CheckpointRestoreEnvOverrideError`). `undefined` for every container
+     * not built via `fromCheckpoint()`.
+     */
+    private checkpointCapturedEnv;
     private handle;
     private backend;
     private mappedPorts;
@@ -61,7 +70,14 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      * captures. `start()` throws `CheckpointBackendMismatchError` before any
      * backend call if the active backend isn't the one that created `cp`, and
      * `ReuseFromCheckpointError` if this container is also marked
-     * `withReuse()` — reuse's identity hash never covers a checkpoint ref.
+     * `withReuse()` — reuse's identity hash never covers a checkpoint ref. On
+     * msb specifically, `start()` also throws `CheckpointRestoreEnvOverrideError`
+     * before any backend call if a further `withEnv()` call actually changes
+     * the env beyond what `cp.spec.env` captured — msb's restore command has
+     * no way to inject env at boot time (see that error's own doc); re-calling
+     * `withEnv()` with the checkpoint's own captured values, unchanged, never
+     * throws. docker is unaffected — an overridden/extended env reaches a
+     * docker restore normally.
      * Once started, a restored container is ordinary in every other respect:
      * fresh host ports, normal reaping-ledger tracking, normal stop.
      */
@@ -292,21 +308,48 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      * state error (same shape as `exec`/`logs`) if this container isn't
      * currently running.
      *
-     * Passing `name` makes this checkpoint NAMED and durable: the ref becomes
-     * deterministic (an absolute `<cacheDir>/checkpoints/rz-ckpt-<name>` path
-     * on microsandbox, `rightsize/checkpoint:<name>` on docker — see
+     * Passing `name` makes this checkpoint NAMED and durable: on docker the ref
+     * becomes deterministic (`rightsize/checkpoint:<name>` — see
      * `checkpointRef` — instead of a random 12-hex suffix), and — only once
      * the backend call below has actually succeeded — a registry entry is written under
      * `<cacheDir>/checkpoints/<name>.json` that `Checkpoints.find`/`list`/
      * `remove` can rediscover later, in this process or a different one. `name`
      * must match `^[a-z0-9][a-z0-9-]{0,40}$`; an invalid name throws
      * `InvalidCheckpointNameError` before any backend call. Checkpointing under
-     * a name that already has a registry entry REPLACES it: the ref is the
-     * same deterministic value either way, so this best-effort clears the old
-     * artifact under that ref before creating the new one, then overwrites the
-     * registry entry — the latest checkpoint under a name always wins.
-     * Omitting `name` keeps the original behavior byte-for-byte: a random ref,
-     * no registry entry, ephemeral.
+     * a name that already has a registry entry REPLACES it: this best-effort
+     * clears whatever artifact the PRIOR checkpoint under `name` actually left
+     * behind, then overwrites the registry entry with the BACKEND'S OWN
+     * EFFECTIVE ref for the fresh checkpoint — the latest checkpoint under a
+     * name always wins. The prior artifact's real location comes from the
+     * existing registry entry itself (when one exists for a backend matching
+     * the currently active one) rather than a recomputed nominal ref: on
+     * docker the two are always the same deterministic value anyway, but on
+     * microsandbox (since 0.7.1) the effective ref is a content-addressed
+     * artifact path the nominal one never predicts (see
+     * `SandboxBackend.createCheckpoint`'s own doc), so reading it back from the
+     * registry is what makes this reliable there too — the same lookup
+     * `Checkpoints.remove(name)` itself uses.
+     *
+     * The PRIOR entry's real ref is only ever removed once the fresh
+     * checkpoint below has actually been created successfully (and, on a
+     * backend whose checkpoint reboots the workload, once the post-checkpoint
+     * re-wait below has succeeded too) — never before. When the prior ref and
+     * the freshly-minted nominal one are the SAME deterministic value (always
+     * true on docker), removing it earlier would just be removing the nominal
+     * ref that `createCheckpoint` is about to reuse anyway, so this method
+     * best-effort clears the nominal ref up front instead (a harmless no-op on
+     * microsandbox, where a name never predicts a real artifact); when the two
+     * differ (microsandbox's content-addressed case, or the rare coincidence
+     * of the two colliding on any backend), the prior ref is left completely
+     * untouched until the new one is confirmed both real and reachable. That
+     * ordering is what keeps a FAILED same-name re-checkpoint from destroying
+     * an otherwise-good, previously-restorable checkpoint: on any backend, a
+     * `createCheckpoint()` (or post-checkpoint re-wait) that throws leaves both
+     * the prior artifact and its registry entry completely untouched, exactly
+     * as if the failed call had never been attempted. Omitting `name` keeps
+     * the original behavior byte-for-byte: an ephemeral checkpoint with no
+     * registry entry, whose `Checkpoint.ref` is always the backend's own
+     * effective ref.
      *
      * On a backend whose `capabilities.checkpointRestartsWorkload` is `true`
      * (microsandbox: the stop/snapshot/reboot cycle boots a fresh microVM),
@@ -323,6 +366,11 @@ export declare class GenericContainer implements AsyncDisposable, NetworkMember
      * BEFORE the wait-strategy re-run — the wait must gate a container that is
      * fully re-linked, not just booted.
      *
+     * If that re-wait (or the link re-install before it) fails, this container
+     * is torn down to completion via `stop()` — same as a failed `start()` —
+     * before the rejection propagates, so a revived-but-never-ready workload
+     * never sits around as an orphan.
+     *
      * Checkpoints are never auto-reaped (a committed image or a disk snapshot
      * is not a container) — see the checkpoints guide for the manual cleanup
      * one-liners and the `Checkpoints.remove` cleanup affordance.

package/dist/core/generic-container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generic-container.d.ts","sourceRoot":"","sources":["../../src/core/generic-container.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generic-container.d.ts","sourceRoot":"","sources":["../../src/core/generic-container.ts"],"names":[],"mappings":"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"}

package/dist/core/generic-container.js

@@ -4,11 +4,12 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { FreePorts } from "./free-ports.js";
 import { RunId } from "./run-id.js";
+import { nextSandboxName } from "./sandbox-name.js";
 import { Network } from "./network.js";
-import { PortBindConflictError, IsolationRequiredError, CheckpointUnsupportedError, CheckpointBackendMismatchError, ReuseFromCheckpointError, RelativeContainerPathError, BackendError, RootDiskConflictError, TmpfsRootExceedsMemoryError, NetworkDisabledConflictError, TmpfsRootCheckpointError, } from "./errors.js";
+import { PortBindConflictError, IsolationRequiredError, CheckpointUnsupportedError, CheckpointBackendMismatchError, ReuseFromCheckpointError, CheckpointRestoreEnvOverrideError, RelativeContainerPathError, BackendError, RootDiskConflictError, TmpfsRootExceedsMemoryError, NetworkDisabledConflictError, TmpfsRootCheckpointError, } from "./errors.js";
 import { requireValidCheckpointName } from "./checkpoint/name.js";
 import { checkpointRef } from "./checkpoint/ref.js";
-import { toCheckpointRegistrySpec, writeCheckpointRegistryAtomic } from "./checkpoint/registry.js";
+import { toCheckpointRegistrySpec, writeCheckpointRegistryAtomic, readCheckpointRegistry } from "./checkpoint/registry.js";
 import { Wait } from "./wait.js";
 import { registerSyncCleanup, unregisterSyncCleanup } from "./cleanup.js";
 import { Backends } from "./backends.js";
@@ -24,12 +25,29 @@ function requireAbsoluteContainerPath(containerPath) {
         throw new RelativeContainerPathError(containerPath);
     }
 }
-const MAX_START_ATTEMPTS = 5;
-let sequence = 0;
-function nextSequence() {
-    sequence += 1;
-    return sequence;
+/**
+ * Order-insensitive equality for env pairs — `start()`'s only use is telling
+ * "the checkpoint's own captured env, re-applied unchanged" from "the caller
+ * actually changed it" (see `CheckpointRestoreEnvOverrideError`). Compared as
+ * key/value sets rather than positionally: `withEnv()` re-setting an
+ * existing key moves it to the end of `envPairs` (last-write-wins,
+ * insertion-ordered — see `withEnv()`'s own doc), which must not by itself
+ * read as a change.
+ */
+function envPairsEqual(a, b) {
+    const aMap = new Map(a);
+    const bMap = new Map(b);
+    if (aMap.size !== bMap.size) {
+        return false;
+    }
+    for (const [key, value] of aMap) {
+        if (bMap.get(key) !== value) {
+            return false;
+        }
+    }
+    return true;
 }
+const MAX_START_ATTEMPTS = 5;
 /** Typed-first, string-fallback classification: walk the cause chain for a typed conflict, else match the daemon's own wording. */
 function isPortBindConflict(err) {
     let current = err;
@@ -111,6 +129,15 @@ export class GenericContainer {
     requireIsolationRequested = false;
     checkpointRef;
     checkpointSourceBackend;
+    /**
+     * `cp.spec.env` exactly as captured, set once by `fromCheckpoint()` and
+     * never touched again — kept separate from the mutable `envPairs` so
+     * `start()` can tell "the caller re-applied the checkpoint's own env
+     * unchanged" from "the caller actually overrode or extended it" (see
+     * `CheckpointRestoreEnvOverrideError`). `undefined` for every container
+     * not built via `fromCheckpoint()`.
+     */
+    checkpointCapturedEnv;
     handle;
     backend;
     mappedPorts = new Map();
@@ -136,7 +163,14 @@ export class GenericContainer {
      * captures. `start()` throws `CheckpointBackendMismatchError` before any
      * backend call if the active backend isn't the one that created `cp`, and
      * `ReuseFromCheckpointError` if this container is also marked
-     * `withReuse()` — reuse's identity hash never covers a checkpoint ref.
+     * `withReuse()` — reuse's identity hash never covers a checkpoint ref. On
+     * msb specifically, `start()` also throws `CheckpointRestoreEnvOverrideError`
+     * before any backend call if a further `withEnv()` call actually changes
+     * the env beyond what `cp.spec.env` captured — msb's restore command has
+     * no way to inject env at boot time (see that error's own doc); re-calling
+     * `withEnv()` with the checkpoint's own captured values, unchanged, never
+     * throws. docker is unaffected — an overridden/extended env reaches a
+     * docker restore normally.
      * Once started, a restored container is ordinary in every other respect:
      * fresh host ports, normal reaping-ledger tracking, normal stop.
      */
@@ -144,6 +178,7 @@ export class GenericContainer {
         const container = new GenericContainer(cp.ref);
         container.checkpointRef = cp.ref;
         container.checkpointSourceBackend = cp.backend;
+        container.checkpointCapturedEnv = cp.spec.env;
         for (const [key, value] of cp.spec.env) {
             container.withEnv(key, value);
         }
@@ -466,6 +501,20 @@ export class GenericContainer {
         if (this.checkpointSourceBackend !== undefined && this.checkpointSourceBackend !== backend.name) {
             throw new CheckpointBackendMismatchError(this.checkpointSourceBackend, backend.name);
         }
+        // Also before any backend work: msb's restore command has no -e/--env
+        // flag at all (see CheckpointRestoreEnvOverrideError's own doc) — an env
+        // the caller has genuinely changed beyond the checkpoint's own captured
+        // values can never reach a restored msb sandbox, so this refuses rather
+        // than silently booting it without the env the caller asked for. Only
+        // msb is checked: docker's restore is an ordinary create/run against the
+        // committed image, so an overridden env reaches it normally. Re-applying
+        // the checkpoint's own captured env unchanged never throws — only a call
+        // that actually changes what would be sent does.
+        if (this.checkpointRef !== undefined &&
+            backend.name === "microsandbox" &&
+            !envPairsEqual(this.checkpointCapturedEnv ?? [], this.envPairs)) {
+            throw new CheckpointRestoreEnvOverrideError(backend.name);
+        }
         // Only the env-resolved path (never an explicit withBackend() override)
         // drives the reaper: writes this process's run record, sweeps dead runs
         // on first use, and spawns the watchdog. Skipping it for overrides is
@@ -516,7 +565,7 @@ export class GenericContainer {
         try {
             for (let attempt = 0; attempt < MAX_START_ATTEMPTS; attempt++) {
                 const ports = await this.allocatePorts();
-                const name = `rz-${RunId.value}-${nextSequence()}`;
+                const name = nextSandboxName();
                 const spec = this.buildSpec(name, ports);
                 // Appended BEFORE create() — the ledger's `.sandboxes` file is always
                 // a superset of this run's live sandboxes, never a subset. `keepAlive`
@@ -912,21 +961,48 @@ export class GenericContainer {
      * state error (same shape as `exec`/`logs`) if this container isn't
      * currently running.
      *
-     * Passing `name` makes this checkpoint NAMED and durable: the ref becomes
-     * deterministic (an absolute `<cacheDir>/checkpoints/rz-ckpt-<name>` path
-     * on microsandbox, `rightsize/checkpoint:<name>` on docker — see
+     * Passing `name` makes this checkpoint NAMED and durable: on docker the ref
+     * becomes deterministic (`rightsize/checkpoint:<name>` — see
      * `checkpointRef` — instead of a random 12-hex suffix), and — only once
      * the backend call below has actually succeeded — a registry entry is written under
      * `<cacheDir>/checkpoints/<name>.json` that `Checkpoints.find`/`list`/
      * `remove` can rediscover later, in this process or a different one. `name`
      * must match `^[a-z0-9][a-z0-9-]{0,40}$`; an invalid name throws
      * `InvalidCheckpointNameError` before any backend call. Checkpointing under
-     * a name that already has a registry entry REPLACES it: the ref is the
-     * same deterministic value either way, so this best-effort clears the old
-     * artifact under that ref before creating the new one, then overwrites the
-     * registry entry — the latest checkpoint under a name always wins.
-     * Omitting `name` keeps the original behavior byte-for-byte: a random ref,
-     * no registry entry, ephemeral.
+     * a name that already has a registry entry REPLACES it: this best-effort
+     * clears whatever artifact the PRIOR checkpoint under `name` actually left
+     * behind, then overwrites the registry entry with the BACKEND'S OWN
+     * EFFECTIVE ref for the fresh checkpoint — the latest checkpoint under a
+     * name always wins. The prior artifact's real location comes from the
+     * existing registry entry itself (when one exists for a backend matching
+     * the currently active one) rather than a recomputed nominal ref: on
+     * docker the two are always the same deterministic value anyway, but on
+     * microsandbox (since 0.7.1) the effective ref is a content-addressed
+     * artifact path the nominal one never predicts (see
+     * `SandboxBackend.createCheckpoint`'s own doc), so reading it back from the
+     * registry is what makes this reliable there too — the same lookup
+     * `Checkpoints.remove(name)` itself uses.
+     *
+     * The PRIOR entry's real ref is only ever removed once the fresh
+     * checkpoint below has actually been created successfully (and, on a
+     * backend whose checkpoint reboots the workload, once the post-checkpoint
+     * re-wait below has succeeded too) — never before. When the prior ref and
+     * the freshly-minted nominal one are the SAME deterministic value (always
+     * true on docker), removing it earlier would just be removing the nominal
+     * ref that `createCheckpoint` is about to reuse anyway, so this method
+     * best-effort clears the nominal ref up front instead (a harmless no-op on
+     * microsandbox, where a name never predicts a real artifact); when the two
+     * differ (microsandbox's content-addressed case, or the rare coincidence
+     * of the two colliding on any backend), the prior ref is left completely
+     * untouched until the new one is confirmed both real and reachable. That
+     * ordering is what keeps a FAILED same-name re-checkpoint from destroying
+     * an otherwise-good, previously-restorable checkpoint: on any backend, a
+     * `createCheckpoint()` (or post-checkpoint re-wait) that throws leaves both
+     * the prior artifact and its registry entry completely untouched, exactly
+     * as if the failed call had never been attempted. Omitting `name` keeps
+     * the original behavior byte-for-byte: an ephemeral checkpoint with no
+     * registry entry, whose `Checkpoint.ref` is always the backend's own
+     * effective ref.
      *
      * On a backend whose `capabilities.checkpointRestartsWorkload` is `true`
      * (microsandbox: the stop/snapshot/reboot cycle boots a fresh microVM),
@@ -943,6 +1019,11 @@ export class GenericContainer {
      * BEFORE the wait-strategy re-run — the wait must gate a container that is
      * fully re-linked, not just booted.
      *
+     * If that re-wait (or the link re-install before it) fails, this container
+     * is torn down to completion via `stop()` — same as a failed `start()` —
+     * before the rejection propagates, so a revived-but-never-ready workload
+     * never sits around as an orphan.
+     *
      * Checkpoints are never auto-reaped (a committed image or a disk snapshot
      * is not a container) — see the checkpoints guide for the manual cleanup
      * one-liners and the `Checkpoints.remove` cleanup affordance.
@@ -968,33 +1049,147 @@ export class GenericContainer {
             throw new TmpfsRootCheckpointError();
         }
         const ref = checkpointRef(backend.name, name);
+        // Replace semantics: a prior checkpoint under this same name — if any —
+        // is cleared once the new one is confirmed to actually exist (see the
+        // deferred removal after `createCheckpoint`/the post-checkpoint re-wait
+        // below), never before — a failed re-checkpoint must never cost this
+        // container its previously-good, restorable checkpoint. The RELIABLE way
+        // to find where the prior checkpoint actually lives is the registry's
+        // own recorded entry (the same lookup `Checkpoints.remove(name)` uses),
+        // not a freshly-minted nominal ref: on docker the ref is deterministic
+        // from `name`, so the registry entry's `ref` and the nominal one below
+        // are always the same value anyway, but on microsandbox (since 0.7.1)
+        // the EFFECTIVE ref `createCheckpoint` returns is a content-addressed
+        // artifact path the nominal one never determines (see
+        // `SandboxBackend.createCheckpoint`'s own doc) — only the registry's
+        // recorded ref points at the real artifact there. Only consulted when
+        // the entry's own recorded backend matches the CURRENTLY active one — a
+        // foreign-backend ref means nothing to this backend's `removeCheckpoint`,
+        // same gate `find`/`remove` apply to the same mismatch. A missing or
+        // corrupt registry read is treated the same as "no entry" (best-effort:
+        // this must never fail the checkpoint itself), leaving only the
+        // nominal-ref removal below to run.
+        let priorRealRef;
         if (name !== undefined) {
-            // Replace semantics: the ref is deterministic from `name`, so a prior
-            // checkpoint under this same name — if any — sits under this exact
-            // ref. Best-effort clear it before creating the new one.
+            try {
+                const registryRead = await readCheckpointRegistry(cacheDir(), name);
+                if (registryRead.kind === "found" && registryRead.entry.backend === backend.name) {
+                    priorRealRef = registryRead.entry.ref;
+                }
+            }
+            catch {
+                // Swallowed deliberately — see the comment above.
+            }
+            // Best-effort clear the freshly-minted NOMINAL ref up front, before
+            // creating the new checkpoint — exactly what this method did before
+            // the registry lookup above existed. On docker this nominal ref IS the
+            // prior checkpoint's real recorded ref (deterministic from `name`), so
+            // this is the only removal that ever runs there, and it must run here:
+            // `createCheckpoint` is about to reuse this exact ref, so there is no
+            // "after" at which removing it wouldn't also remove the checkpoint
+            // just created. On microsandbox this is a no-op against a path that
+            // was never real, same as before this method ever read the registry —
+            // so nothing new is destroyed here before the new checkpoint's success
+            // is confirmed.
             await swallow(() => backend.removeCheckpoint(ref));
         }
-        await backend.createCheckpoint(handle, ref);
+        // The EFFECTIVE ref: on docker this is always `ref` itself; on
+        // microsandbox (since 0.7.1) it is whatever real artifact path
+        // `createCheckpoint` discovered from `msb snapshot create`'s own stdout
+        // — never necessarily `ref`. Everything downstream (the registry entry,
+        // the returned `Checkpoint`) uses this, not the working `ref`.
+        //
+        // Captured BEFORE the call: a backend whose checkpoint reboots the
+        // workload under a fresh identity (msb's `createCheckpoint`, see its own
+        // doc) mutates `handle.id` IN PLACE once that reboot succeeds — the same
+        // carve-out `SandboxBackend.createCheckpoint`'s own interface doc
+        // documents. `registerSyncCleanup` (see start(), above) keyed its exit-path
+        // teardown entry by the OLD id; if the id just changed, that registration
+        // must be re-keyed to the new one too, or the old entry leaks in
+        // `cleanup.ts`'s registry forever (stop() below only ever unregisters by
+        // the CURRENT `handle.id`, which after a rename no longer matches what
+        // was registered) — silently breaking both the exit-path teardown for
+        // this container AND `liveContainers()`/diagnostics, which read that same
+        // registry.
+        const preCheckpointHandleId = handle.id;
+        const effectiveRef = await backend.createCheckpoint(handle, ref);
+        if (handle.id !== preCheckpointHandleId && !handle.spec.keepAlive) {
+            // Mirrors start()'s own keepAlive exclusion: a keepAlive container was
+            // never registered in the first place, so there is nothing to re-key.
+            // The cleanup closure below reads `handle.id` dynamically (see
+            // start()'s own registerSyncCleanup call), so re-registering it under
+            // the new id is automatically correct without capturing anything else.
+            unregisterSyncCleanup(preCheckpointHandleId);
+            registerSyncCleanup(handle, backend, () => backend.cleanupSync(handle.id));
+        }
         if (backend.capabilities.checkpointRestartsWorkload) {
-            if (this.installedNetworkLinks.length > 0) {
-                await backend.installNetworkLinks(handle, this.installedNetworkLinks);
+            // The backend checkpoint call above already succeeded — the artifact
+            // exists — but the reboot it triggered can still leave this container
+            // unusable: a revived workload that never becomes ready. Same shape as
+            // start()'s own post-boot wait (line ~722): a failure here must not
+            // leak the freshly-spawned workload (msb's revived `exec` child sits
+            // in `handle`'s attached slot from the moment the reboot reaches
+            // Running, well before this wait ever resolves). Tear this container
+            // down to completion via the same this.stop() start() uses, so the
+            // handle's attached child — and the sandbox itself — never outlive
+            // this rejection, before rethrowing.
+            try {
+                if (this.installedNetworkLinks.length > 0) {
+                    await backend.installNetworkLinks(handle, this.installedNetworkLinks);
+                }
+                await this.waitStrategy.waitUntilReady(this.asWaitTarget());
+            }
+            catch (err) {
+                await this.stop();
+                throw err;
             }
-            await this.waitStrategy.waitUntilReady(this.asWaitTarget());
         }
+        // The workload argv the backend captured from the guest during the
+        // createCheckpoint() call just above, when `handle.spec.command` was
+        // undefined — see `SandboxBackend.capturedWorkloadCommand`'s own doc.
+        // `undefined` on every backend that never captures one (docker, or msb
+        // when the source container already carried an explicit command).
+        const capturedCommand = backend.capturedWorkloadCommand?.(handle);
         if (name !== undefined) {
+            // Only reached once the fresh checkpoint above is confirmed both real
+            // (createCheckpoint succeeded) and reachable (the post-checkpoint
+            // re-wait above, when applicable, succeeded too) — a failure at either
+            // point already threw and returned above, before any of this ran. The
+            // PRIOR checkpoint's real recorded ref (see the registry lookup
+            // before createCheckpoint) is best-effort removed here, now that it is
+            // safe to: never when it's the SAME ref as the nominal one already
+            // cleared above (docker — clearing it again here would target the
+            // fresh checkpoint `createCheckpoint` just reused that exact ref for),
+            // and never when it happens to equal the fresh checkpoint's own
+            // EFFECTIVE ref (the rare case of two checkpoints content-addressing
+            // to the very same artifact on microsandbox — removing it would delete
+            // the checkpoint this call just created, not a prior one).
+            if (priorRealRef !== undefined && priorRealRef !== ref && priorRealRef !== effectiveRef) {
+                const realRef = priorRealRef;
+                await swallow(() => backend.removeCheckpoint(realRef));
+            }
             // Only after the backend checkpoint above has actually succeeded — a
             // failed createCheckpoint() already threw, so a registry entry is
             // never written for a checkpoint that doesn't exist.
             const entry = {
                 name,
-                ref,
+                ref: effectiveRef,
                 backend: backend.name,
                 createdIso: new Date().toISOString(),
                 spec: toCheckpointRegistrySpec(handle.spec),
+                ...(capturedCommand !== undefined ? { capturedCommand } : {}),
             };
             await writeCheckpointRegistryAtomic(cacheDir(), name, entry);
         }
-        return { ref, backend: backend.name, spec: handle.spec };
+        // `handle.spec.command` already covers an explicit command; only
+        // substitute the captured fallback when the source had none, so a later
+        // `fromCheckpoint(cp).start()` on THIS in-memory `Checkpoint` — unnamed
+        // or named, same process or not — already carries the fully-resolved
+        // workload argv a restore-side backend needs to revive it, the same
+        // merge `fromCheckpointRegistryEntry` applies for a registry-mediated
+        // restore.
+        const effectiveSpec = handle.spec.command !== undefined || capturedCommand === undefined ? handle.spec : { ...handle.spec, command: capturedCommand };
+        return { ref: effectiveRef, backend: backend.name, spec: effectiveSpec };
     }
     /**
      * Copies a host file or directory into this running container at