rightsize 0.7.9 → 0.7.12

package/dist/backend-msb/backend.js

@@ -2,7 +2,10 @@ import { spawn, spawnSync } from "node:child_process";
 import * as readline from "node:readline";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { BackendError, PortBindConflictError, UnsupportedByBackendError, TmpfsRootCheckpointError } from "../core/errors.js";
+import { BackendError, PortBindConflictError, UnsupportedByBackendError, TmpfsRootCheckpointError, CheckpointWorkloadCommandMissingError, } from "../core/errors.js";
+import { cacheDir } from "../core/cache-dir.js";
+import { nextSandboxName } from "../core/sandbox-name.js";
+import { trackSandbox, untrackSandbox } from "../core/reaper/init.js";
 import { MsbCommands } from "./commands.js";
 import { runningNames, statusOf } from "./ls-json.js";
 import { hasSandboxStartedMarker } from "./fast-exit.js";
@@ -12,14 +15,26 @@ import { isImageCacheCorruption } from "./image-cache.js";
 import { isMsbStateDbError } from "./state-db.js";
 import { isAgentEndpointNotReady } from "./agent-endpoint.js";
 import { isSnapshotNotFoundError } from "./snapshot-not-found.js";
-import { isSnapshotAlreadyExistsError, parseImportedDigestDirName } from "./snapshot-import.js";
+import { isSnapshotAlreadyExistsError, parseImportedArtifactPath } from "./snapshot-import.js";
 import { isSnapshotSaveAccessDeniedFailure, salvageStagedArchive } from "./snapshot-save-fsync.js";
-import { parseSnapshotList, confirmDigestDirNamePresent } from "./snapshot-list.js";
+import { parseSnapshotCreateArtifactPath } from "./snapshot-create.js";
+import { isSnapshotHeadRemovalRefused } from "./snapshot-rm.js";
 import { undeliveredLines } from "./follow-replay.js";
-import { requireNoDuplicateGuestPorts, requireAliasesAreValid, hostsAliasScript } from "./network-links.js";
+import { requireNoDuplicateGuestPorts, requireAliasesAreValid, hostsAliasScript, udpForwarderProbeScript, installUdpForwarderScript, udpReadinessProbeScript, udpForwarderLogPath, } from "./network-links.js";
 import { ExecTunnel } from "./exec-tunnel.js";
+import { isRestoreAccessDeniedFailure } from "./restore-access-denied.js";
+import { isSandboxAlreadyExistsFailure } from "./sandbox-already-exists.js";
+import { realRestoreBroker, } from "./restore-broker.js";
 const FIRST_RUN_PULL_TIMEOUT_MS = 600_000; // a cold pull can be slow
 const READINESS_POLL_MS = 300;
+// A UDP link's forwarder prints nothing on bind (`nc -u -l` is silent), so
+// readiness is polled against /proc/net/udp{,6} directly rather than
+// inferred from the launch exec alone — short interval, short budget: the
+// script's own listener loop starts within a handful of shell built-ins of
+// launching, never a cold pull or a poll-driven state transition like the
+// boot-readiness constants above.
+const UDP_LINK_READINESS_POLL_MS = 100;
+const UDP_LINK_READINESS_TIMEOUT_MS = 5_000;
 const STOP_TIMEOUT_MS = 60_000;
 const EXEC_TIMEOUT_MS = 120_000;
 // How long an exec keeps retrying while the guest agent's endpoint has not
@@ -44,6 +59,51 @@ const COPY_TIMEOUT_MS = 120_000;
 // already confirmed no longer Running. Never a wait-for-content budget: a
 // stopped sandbox's log cannot grow, so the first successful fetch is final.
 const TERMINAL_FETCH_FAILURE_BUDGET_MS = 10_000;
+// How long `reviveWorkload` gives a freshly-spawned workload-revival exec
+// child to prove it isn't an immediate boot failure before treating it as
+// the ordinary long-lived case. Unlike `bootRunOnce`'s own attached child,
+// there is no separate "reached Running" signal to poll for here — the
+// SANDBOX already reports Running regardless of whether this exec succeeds
+// — so a short settle window is what that same exit-vs-success race
+// collapses to when the only observable signal left is the child's own
+// exit. A few multiples of the ordinary poll cadence is plenty: a failing
+// workload (bad command, missing binary, an immediate usage error) exits
+// within milliseconds of spawn, while a genuine long-lived server never
+// exits on its own at all.
+const EXEC_REVIVE_SETTLE_MS = READINESS_POLL_MS * 3;
+// Bounded retry policy for `msb restore` hitting a Windows access-denied
+// failure on its own just-written snapshot artifact (see
+// `isRestoreAccessDeniedFailure`) — a brief file-handle release lag that
+// normally clears within one retry, so several short-backoff attempts cover
+// the real cases without masking a genuinely stuck lock.
+const RESTORE_ACCESS_DENIED_RETRY_LIMIT = 3;
+const RESTORE_ACCESS_DENIED_RETRY_DELAY_MS = 500;
+/**
+ * How long `createCheckpoint`'s own reboot step keeps retrying msb's
+ * "sandbox already exists" refusal (see `isSandboxAlreadyExistsFailure`) and
+ * its Windows access-denied refusal on the just-written snapshot artifact
+ * (see `isRestoreAccessDeniedFailure`), and the pause between attempts — the
+ * same install-lock-poll shape `INSTALL_LOCK_RETRY_BUDGET_MS`/
+ * `INSTALL_LOCK_RETRY_DELAY_MS` already use. EMPIRICALLY VERIFIED against a
+ * real msb 0.7.1 binary (an isolated `MSB_HOME` testbed): `msb restore
+ * --name X` validates the artifact FIRST — an integrity failure exits 1 and
+ * leaves NO sandbox record — but a failure AFTER validation (matching either
+ * classified signature above) leaves `X` behind as a STOPPED SANDBOX RECORD
+ * visible in `msb ls`, and msb's own restore-time collision check
+ * (`existing.is_some() || dir_exists`, `prepare_create_target` in
+ * `sdk/rust/lib/backend/local/sandbox/create.rs`) then refuses any retry
+ * under that SAME name — on Windows CI this refusal has been observed
+ * holding for the whole span of a same-name retry loop under load. Each
+ * retry attempt therefore mints a BRAND NEW name rather than reusing the one
+ * that just failed (see `rebootUnderFreshName`), which sidesteps that exact
+ * collision structurally — a name nothing else has ever used cannot collide
+ * with a record or a lingering on-disk directory belonging to a name nothing
+ * will ever restore under again. This budget bounds how long that
+ * fresh-name retry loop as a whole keeps advancing before giving up, not a
+ * single name's own collision.
+ */
+const CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_BUDGET_MS = 30_000;
+const CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_DELAY_MS = 2_000;
 /**
  * The boot failure `start()` heals and retries — carries the `msb run`
  * child's combined output for the second-failure diagnostic. Internal to the
@@ -106,6 +166,45 @@ class InstallLockActiveError extends Error {
         this.output = output;
     }
 }
+/**
+ * Restore-path classified failure for `isRestoreAccessDeniedFailure` — a
+ * Windows-only `msb restore` transient against its own just-written
+ * snapshot artifact (see that function's own doc). Internal to the boot
+ * path, like its siblings above; `bootClassified` owns the bounded-retry
+ * policy. Only ever thrown from `bootRestoreOnce`, since it is a restore
+ * invocation's own failure signature — an ordinary `run` boot never touches
+ * a snapshot artifact at all.
+ */
+class RestoreAccessDeniedError extends Error {
+    output;
+    constructor(output) {
+        super(`msb restore access-denied on its own snapshot artifact:\n${output}`);
+        this.output = output;
+    }
+}
+/**
+ * Restore-path classified failure for `isSandboxAlreadyExistsFailure` — msb
+ * refusing `restore` because a sandbox under this name already exists (its
+ * database record, its on-disk directory, or both — see that function's own
+ * doc). Internal to the boot path, like its siblings above; only ever
+ * thrown from `bootRestoreOnce`. `bootClassified` itself never retries this
+ * one (unlike its siblings) — it simply propagates, so the ordinary
+ * `start()` path (a `GenericContainer.fromCheckpoint(cp).start()` restore
+ * of a name that turns out to still be live) surfaces it immediately, a
+ * real error. Only `createCheckpoint`'s own reboot step, via
+ * `rebootUnderFreshName`, retries it — under a NEWLY minted name each time,
+ * never the one that just collided (see that method's own doc) — a caller
+ * reusing a live name is never this backend's own race to hide, but the
+ * checkpoint cycle's own historical `rm`-then-restore of the SAME name was
+ * exactly that race.
+ */
+class SandboxAlreadyExistsError extends Error {
+    output;
+    constructor(output) {
+        super(`msb restore refused — a sandbox with this name already exists:\n${output}`);
+        this.output = output;
+    }
+}
 /**
  * How long to wait before retrying a boot that hit msb's state-database
  * error — enough for a winning concurrent invocation's migration transaction
@@ -192,16 +291,17 @@ function describeHeal(heal) {
 }
 /**
  * True when `ref` (an absolute path ref) looks like a checkpoint artifact
- * this backend itself would have written — a directory named `rz-ckpt-*`
- * (`checkpointRef`'s own prefix) containing a `snapshot.json` file, the same
- * shape `hasCheckpoint` checks for. `removeCheckpoint`'s recursive delete is
- * gated on this: `ref` is caller-supplied (a corrupt or hand-edited registry
- * entry), and skipping the shape check would let an arbitrary path get
- * `fs.rm(..., { recursive: true })`'d just because it happened to be passed
- * in as a "ref".
+ * this backend itself would have written — a directory named `snap_<hex>`
+ * (msb's own snapshot-store naming since 0.7.1 — see
+ * `parseSnapshotCreateArtifactPath`) containing a `snapshot.json` file, the
+ * same shape `hasCheckpoint` checks for. `removeCheckpoint`'s recursive
+ * delete is gated on this: `ref` is caller-supplied (a corrupt or
+ * hand-edited registry entry), and skipping the shape check would let an
+ * arbitrary path get `fs.rm(..., { recursive: true })`'d just because it
+ * happened to be passed in as a "ref".
  */
 async function looksLikeCheckpointArtifactDir(ref) {
-    if (!path.basename(ref).startsWith("rz-ckpt-")) {
+    if (!/^snap_[0-9a-f]+$/i.test(path.basename(ref))) {
         return false;
     }
     const stat = await fs.stat(ref).catch(() => undefined);
@@ -234,10 +334,97 @@ function drainTail(stream, tail) {
         rl.on("close", () => resolveDrain());
     });
 }
+/**
+ * `drainTail`'s sibling for text this backend already has in hand rather
+ * than a live stream — a brokered restore's own combined output
+ * (`launchRestoreViaBroker`), or a diagnostic note about the broker itself.
+ * Same `TAIL_LINES` cap, same shift-oldest behavior, so a brokered attempt's
+ * pre-Running diagnostics tail looks exactly like a direct attempt's
+ * regardless of which path produced it.
+ */
+function pushLinesToTail(tail, text) {
+    for (const line of text.split("\n")) {
+        tail.push(line);
+        if (tail.length > TAIL_LINES) {
+            tail.shift();
+        }
+    }
+}
+/**
+ * Busybox-ash-compatible: finds the first non-kernel child of PID 1 in the
+ * guest and prints its `/proc/<pid>/cmdline` RAW — NUL-separated with a
+ * trailing NUL, the kernel's own on-disk shape, never re-encoded by this
+ * script itself — to stdout, exit 0; exits 1 if none is found. Walks
+ * every `/proc/<pid>/stat` in NUMERIC pid order (`ls | sort -n`, since a bare
+ * shell glob sorts lexically — "10" before "2" — which is wrong for "the
+ * first child") and, for each, reads field 4 (`ppid`, 1-indexed per
+ * `/proc/pid/stat`'s own `pid (comm) state ppid ...` layout), skipping any
+ * whose `ppid` isn't `1`. `comm` is split out via the FIRST `(` and the LAST
+ * `)` (`${st#*(}` / `${comm%)*}`, both plain POSIX parameter expansion, no
+ * `extglob` needed) rather than a naive single-`(`/`)` split, since a
+ * process name may itself contain spaces (or, in principle, parens) — the
+ * same robustness a greedy sed capture between the first "(" and the last
+ * ")" would get. Two names are excluded even though
+ * their `ppid` may show `1`: the guest's own init (`init.krun`) and any
+ * bracketed kernel-thread name (`[kworker/0:1]`, `[ksoftirqd/0]`, ...) — the
+ * shape every kernel thread's `comm` renders as. Read by `MsbCliBackend`'s
+ * own `createCheckpoint`, BEFORE it stops the source sandbox — see that
+ * method's own doc — via a plain `exec`, never anything backend-specific
+ * beyond that: this is guest-side shell, not msb CLI surface.
+ */
+const CAPTURE_WORKLOAD_CMDLINE_SCRIPT = [
+    // A marker comment, not functional shell — lets the msb fixture (and any
+    // future test double) recognize this exact exec call by its script
+    // content rather than guessing from argv shape alone.
+    "# rightsize:capture-workload-cmdline",
+    "for pid in $(ls /proc 2>/dev/null | grep -E '^[0-9]+$' | sort -n); do",
+    "  st=$(cat /proc/$pid/stat 2>/dev/null) || continue",
+    "  rest=${st##*) }",
+    "  set -- $rest",
+    "  ppid=$2",
+    "  if [ \"$ppid\" != \"1\" ]; then continue; fi",
+    "  comm=${st#*(}",
+    "  comm=${comm%)*}",
+    "  case \"$comm\" in",
+    "    init.krun|\\[*\\]) continue ;;",
+    "  esac",
+    "  cat /proc/$pid/cmdline",
+    "  exit 0",
+    "done",
+    "exit 1",
+].join("\n");
+/**
+ * Parses `CAPTURE_WORKLOAD_CMDLINE_SCRIPT`'s stdout — the discovered
+ * process's raw `/proc/<pid>/cmdline` bytes, NUL-separated with a trailing
+ * NUL — into an argv. `captureGuestWorkloadCmdline` fetches this through the
+ * ordinary `exec()` (`invoke()`'s line-based reconstruction, not
+ * `fetchStdoutExact`'s byte-exact one — see that function's own doc), which
+ * appends a trailing `\n` to any non-empty output; since the guest script's
+ * own output never contains a real newline of its own (it is exactly the
+ * NUL-joined cmdline bytes), that single appended `\n` is always the whole
+ * of `invoke()`'s own last "line" and is stripped here before splitting,
+ * rather than being read back as a bogus trailing argv element. `undefined`
+ * on anything that isn't a clean, non-empty argv after that: empty output
+ * (the script found no matching child, exited 1, or the guest's own cmdline
+ * was itself empty) or content that splits into zero non-empty tokens. Never
+ * throws — see `captureGuestWorkloadCmdline`'s own doc on why a capture
+ * failure must never fail the checkpoint that triggered it.
+ */
+function parseCapturedWorkloadCmdline(stdout) {
+    if (stdout.length === 0) {
+        return undefined;
+    }
+    const withoutTrailingNewline = stdout.endsWith("\n") ? stdout.slice(0, -1) : stdout;
+    const parts = withoutTrailingNewline.split("\0").filter((s) => s.length > 0);
+    return parts.length > 0 ? parts : undefined;
+}
 /**
  * The attached-mode CLI driver: every sandbox this backend starts runs as a
- * held child process (`msb run`, no `-d`) because detached mode never
- * executes the image's own ENTRYPOINT/CMD — only attached mode does.
+ * held child process (`msb run`, no `-d`). Detached mode (`msb run -d`) runs
+ * the image's own ENTRYPOINT/CMD too, so this isn't about getting the
+ * workload to start — it's supervision: the held child gives this backend
+ * child-exit-based death detection and a place to capture pre-Running boot
+ * diagnostics, neither of which a detached boot provides on its own.
  * Readiness is never inferred from that child's own output; it comes from
  * polling `msb ls --format json` until the name shows `"Running"`. The
  * attached child's stdout/stderr carries msb's own boot diagnostics and is
@@ -265,6 +452,10 @@ export class MsbCliBackend {
         /** The stop/snapshot/reboot cycle reboots the microVM — the workload restarts. */
         checkpointRestartsWorkload: true,
     };
+    // Both keyed by a sandbox's CURRENT name (== SandboxHandle.id) — normally
+    // stable for a handle's whole lifetime, except across createCheckpoint's
+    // own reboot, which re-keys both from the source sandbox's name to the
+    // fresh one it boots under (see that method's own doc).
     handles = new Map();
     startedNames = new Set();
     // Mirrors msbPathPromise's eventual value as soon as it settles, purely so
@@ -272,8 +463,35 @@ export class MsbCliBackend {
     // anything) has a best-effort synchronous read of it. Never written to
     // except by this one .then() below; never awaited anywhere else.
     resolvedMsbPath;
-    constructor(msbPathPromise) {
+    // Test-only override seam for rebootUnderFreshName's own budget/delay
+    // — defaults to the real CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_BUDGET_MS/
+    // _DELAY_MS constants so production behavior is unchanged. Without this, a
+    // budget-exhaustion red-proof would mean a unit test actually blocking for
+    // the real ~30s; a test reaches these the same way it already reaches
+    // `handles`/`startedNames` elsewhere in this suite — an unsafe cast — to
+    // shrink them to milliseconds instead.
+    checkpointRebootAlreadyExistsRetryBudgetMs = CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_BUDGET_MS;
+    checkpointRebootAlreadyExistsRetryDelayMs = CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_DELAY_MS;
+    // POLICY v2's broker escalation — see `RestoreLaunchMode`/`restore-broker.ts`.
+    restoreBroker;
+    // Test-only override for the Windows-only escalation gate
+    // (`isWindowsPlatform`) — `undefined` in production, where the real
+    // `process.platform` always decides. Reached the same unsafe-cast way this
+    // suite already reaches `checkpointRebootAlreadyExistsRetryBudgetMs`
+    // above, so both the escalation trigger AND the "non-Windows never
+    // brokers" invariant are exercisable without an actual Windows host.
+    platformOverrideForTests = undefined;
+    // Test-only override seam for installUdpLink's own readiness poll
+    // interval/budget — defaults to the real UDP_LINK_READINESS_POLL_MS/
+    // _TIMEOUT_MS constants so production behavior is unchanged. Reached the
+    // same unsafe-cast way this suite already reaches
+    // checkpointRebootAlreadyExistsRetryBudgetMs above, so a readiness-timeout
+    // red-proof runs in milliseconds rather than the real 5s.
+    udpLinkReadinessPollMs = UDP_LINK_READINESS_POLL_MS;
+    udpLinkReadinessTimeoutMs = UDP_LINK_READINESS_TIMEOUT_MS;
+    constructor(msbPathPromise, options = {}) {
         this.msbPathPromise = msbPathPromise;
+        this.restoreBroker = options.restoreBroker ?? realRestoreBroker;
         this.msbPathPromise.then((p) => {
             this.resolvedMsbPath = p;
         }, () => {
@@ -282,11 +500,24 @@ export class MsbCliBackend {
             // when it awaits msbPathPromise itself.
         });
     }
+    /**
+     * Whether this process should treat itself as running on Windows for
+     * POLICY v2's broker-escalation gate — `process.platform === "win32"` in
+     * production, or `platformOverrideForTests` when a test has set it. The
+     * ONLY thing this gates is whether `rebootUnderFreshName`/
+     * `retryRestoreAfterAccessDenied` ever set `RestoreLaunchMode` to
+     * `"broker"`; `bootOnce`/`bootRestoreOnce` themselves stay platform-
+     * agnostic dispatchers on whatever mode they're handed, so the broker path
+     * itself is exercisable on any host once a test picks it explicitly.
+     */
+    isWindowsPlatform() {
+        return (this.platformOverrideForTests ?? process.platform) === "win32";
+    }
     async msbPath() {
         return this.msbPathPromise;
     }
     async create(spec) {
-        this.handles.set(spec.name, { attached: undefined, attachedExited: false, resources: [], logTail: [] });
+        this.handles.set(spec.name, { attached: undefined, attachedExited: false, resources: [], logTail: [], capturedCommand: undefined });
         return { id: spec.name, spec };
     }
     /**
@@ -331,14 +562,48 @@ export class MsbCliBackend {
      * knows: the install-lock poll, the one-shot state-database retry, and the
      * one-shot image-cache heal. Both the ordinary `start()` path and the
      * checkpoint cycle's post-snapshot reboot come through here — a reboot
-     * from a snapshot is as exposed to msb's transients as any other boot,
-     * and skipping the classification there turned a passing install-lock
-     * poll into an immediate checkpoint failure on a live Windows run.
+     * from a snapshot (now `msb restore ...`, see `bootRestoreOnce`) is
+     * as exposed to msb's transients as any other boot, and skipping the
+     * classification there turned a passing install-lock poll into an
+     * immediate checkpoint failure on a live Windows run. The image-cache heal
+     * targets `handle.spec.image`, which for a restore is the checkpoint ref
+     * GenericContainer.fromCheckpoint() threaded through as the builder's
+     * "image" — never a real OCI reference `msb image remove` can act on
+     * meaningfully; this predates the 0.7.1 migration (the same was true of
+     * `--from-snapshot` boots) and is unchanged here.
+     *
+     * `retryAccessDenied` (default `true`) gates ONLY the
+     * `RestoreAccessDeniedError` branch below — every other classified retry
+     * always runs regardless. The ordinary `start()` path (including a plain
+     * `GenericContainer.fromCheckpoint(cp).start()` restore) leaves it at the
+     * default, delegating to `retryRestoreAfterAccessDenied` — see that
+     * method's own doc for why it, like `createCheckpoint`'s own reboot, must
+     * mint a fresh name for every retry rather than reusing the one that just
+     * failed: the live-verified dossier this backend's fresh-naming behavior
+     * is built from says a restore that fails PAST msb's own artifact
+     * validation (this access-denied signature included) leaves the attempted
+     * name behind as a stopped sandbox record, so a same-name retry only ever
+     * collides with that record instead of retrying the actual transient.
+     * `createCheckpoint`'s own reboot (`rebootUnderFreshName`) passes `false`:
+     * it owns this error class itself, one layer up, via its own fresh-naming
+     * loop, and needs this error to propagate on the first hit rather than
+     * being retried here at all.
+     *
+     * `restoreLaunchMode` (default `"direct"`) is threaded straight down to
+     * every `bootOnce` call this method makes, including its own internal
+     * install-lock/state-db/image-cache retries — POLICY v2's broker
+     * escalation, once triggered by the caller (`rebootUnderFreshName`/
+     * `retryRestoreAfterAccessDenied`), applies to EVERY remaining attempt of
+     * that reboot, not just the ones those callers themselves loop over, so an
+     * install-lock hit mid-brokered-attempt must retry brokered too rather
+     * than silently reverting to a direct spawn. See `RestoreLaunchMode`'s own
+     * doc.
      */
-    async bootClassified(msbPath, handle, state) {
+    async bootClassified(msbPath, handle, state, options = { retryAccessDenied: true }) {
+        const restoreLaunchMode = options.restoreLaunchMode ?? "direct";
         let firstOutput;
         try {
-            await this.bootOnce(msbPath, handle, state);
+            await this.bootOnce(msbPath, handle, state, restoreLaunchMode);
             return;
         }
         catch (first) {
@@ -355,7 +620,7 @@ export class MsbCliBackend {
                 while (Date.now() < deadline) {
                     await sleep(INSTALL_LOCK_RETRY_DELAY_MS);
                     try {
-                        await this.bootOnce(msbPath, handle, state);
+                        await this.bootOnce(msbPath, handle, state, restoreLaunchMode);
                         return;
                     }
                     catch (again) {
@@ -377,7 +642,7 @@ export class MsbCliBackend {
                 // image-cache heal below.
                 await sleep(STATE_DB_RETRY_DELAY_MS);
                 try {
-                    await this.bootOnce(msbPath, handle, state);
+                    await this.bootOnce(msbPath, handle, state, restoreLaunchMode);
                     return;
                 }
                 catch (second) {
@@ -390,6 +655,17 @@ export class MsbCliBackend {
                         `host.\nfirst attempt:\n${first.output}\nafter retry:\n${second.output}`);
                 }
             }
+            if (first instanceof RestoreAccessDeniedError) {
+                if (!options.retryAccessDenied) {
+                    // The checkpoint reboot's own fresh-naming retry
+                    // (`rebootUnderFreshName`) owns this error class itself, one layer
+                    // up — see this method's own doc on `retryAccessDenied`. Propagate
+                    // immediately rather than retrying it here at all.
+                    throw first;
+                }
+                await this.retryRestoreAfterAccessDenied(msbPath, handle, state, first);
+                return;
+            }
             if (!(first instanceof ImageCacheCorruptionError)) {
                 throw first;
             }
@@ -397,7 +673,7 @@ export class MsbCliBackend {
         }
         const heal = await invoke(msbPath, MsbCommands.imageRemove(handle.spec.image), STOP_TIMEOUT_MS).catch((e) => e);
         try {
-            await this.bootOnce(msbPath, handle, state);
+            await this.bootOnce(msbPath, handle, state, restoreLaunchMode);
         }
         catch (second) {
             if (!(second instanceof ImageCacheCorruptionError)) {
@@ -411,30 +687,50 @@ export class MsbCliBackend {
         }
     }
     /**
-     * One boot attempt: spawns the attached `msb run` child and polls until the
-     * sandbox reaches Running. `state.attached` and (for non-keepAlive specs)
-     * `startedNames` are populated only on success; on any failure the child is reaped here (for
+     * One boot attempt, dispatched by shape: an ordinary spec (no
+     * `checkpointRef`) drives `run()`'s ATTACHED supervision model
+     * (`bootRunOnce`); a checkpoint-restore spec drives `msb restore`'s
+     * fundamentally different DETACHED shape (`bootRestoreOnce`) — see each
+     * method's own doc. Resets the per-attempt diagnostics tail before either:
+     * a retried boot must not blend its tail with the failed attempt's.
+     * `restoreLaunchMode` is passed straight through to `bootRestoreOnce`
+     * (irrelevant to `bootRunOnce`'s own ordinary `run` path, which never
+     * brokers — see `RestoreLaunchMode`'s own doc).
+     */
+    async bootOnce(msbPath, handle, state, restoreLaunchMode = "direct") {
+        state.logTail = [];
+        state.attachedExited = false;
+        if (handle.spec.checkpointRef !== undefined) {
+            await this.bootRestoreOnce(msbPath, handle, state, restoreLaunchMode);
+            return;
+        }
+        await this.bootRunOnce(msbPath, handle, state);
+    }
+    /**
+     * One RUN boot attempt: spawns ATTACHED `msb run`, which stays alive as
+     * the sandbox's own supervisor for its whole lifetime, and polls
+     * `msb ls --format json` until the name shows Running.
+     *
+     * `state.attached` and (for non-keepAlive specs) `startedNames` are
+     * populated only on success; on any failure the child is reaped here (for
      * the classified early-exit failures it has already exited; a readiness
      * timeout leaves it alive and it is hard-killed) so a failed attempt leaves
      * no live process or registered cleanup state behind — the caller owns
-     * retry policy, never cleanup (an exit-0 fast-exit success is the one
-     * exception: it IS success, so `state.attached`/`startedNames` ARE
-     * populated for it — see below). An early exit is classified from the
-     * child's combined output: the image-cache-corruption signature throws
-     * `ImageCacheCorruptionError` (the one failure `start()` heals and
-     * retries), a host-port bind conflict throws `PortBindConflictError`, and
-     * otherwise — if the exit code was 0 — `isCompletedFastExit` gets a chance
-     * to reclassify the exit as a workload that ran to completion before this
-     * poll loop could ever observe Running (msb 0.6.16's convergent-lifecycle
-     * rework; see that method's own doc); anything else surfaces the raw
-     * output as an ordinary boot failure, unchanged.
+     * retry policy, never cleanup (an exit-0 success without a live child is
+     * the one exception: the fast-exit case below, see `isCompletedFastExit`'s
+     * own doc). An early exit is classified from the child's combined output:
+     * the image-cache-corruption signature throws `ImageCacheCorruptionError`
+     * (the one failure `start()` heals and retries), a host-port bind conflict
+     * throws `PortBindConflictError`, and otherwise — if the exit code was 0 —
+     * `isCompletedFastExit` gets a chance to reclassify the exit as a workload
+     * that ran to completion before this poll loop could ever observe Running
+     * (msb 0.6.16's convergent-lifecycle rework; see that method's own doc);
+     * anything else surfaces the raw output as an ordinary boot failure,
+     * unchanged.
      */
-    async bootOnce(msbPath, handle, state) {
-        // Fresh per-attempt diagnostics: a retried boot must not blend its tail
-        // with the failed attempt's.
-        state.logTail = [];
-        state.attachedExited = false;
-        const child = spawn(msbPath, MsbCommands.run(handle.spec), { stdio: [CLOSED_STDIN, "pipe", "pipe"] });
+    async bootRunOnce(msbPath, handle, state) {
+        const argv = MsbCommands.run(handle.spec);
+        const child = spawn(msbPath, argv, { stdio: [CLOSED_STDIN, "pipe", "pipe"] });
         // Merge stdout+stderr into one tail, kept only for the boot diagnostics
         // below: this pipe is the sole carrier of msb's own output (registry/pull
         // errors, crash output printed before the sandbox exists). It is not a
@@ -479,8 +775,9 @@ export class MsbCliBackend {
                     }
                     return;
                 }
-                throw new BackendError(`msb run for sandbox ${handle.id} exited (code ${exited.code ?? "unknown"}) before reaching ` +
-                    `Running — check the image entrypoint and 'msb run' output below:\n${output}`);
+                throw new BackendError(`msb run for sandbox ${handle.id} exited (code ${exited.code ?? "unknown"}) ` +
+                    `before reaching Running — check the image entrypoint and 'msb run' ` +
+                    `output below:\n${output}`);
             }
             if ((await this.runningSandboxNames(msbPath)).has(handle.id)) {
                 state.attached = child;
@@ -501,9 +798,400 @@ export class MsbCliBackend {
             await sleep(READINESS_POLL_MS);
         }
     }
+    /**
+     * One RESTORE boot attempt. `msb restore` is not `run`'s attached
+     * supervision model at all — EMPIRICALLY VERIFIED against msb 0.7.1 (its
+     * own `restore.rs` doc: "Restore a snapshot into a new detached
+     * sandbox"), the restore CLI process exits — typically within seconds,
+     * often with little or no stdout — the INSTANT activation succeeds, while
+     * the sandbox keeps booting in the background and only reaches Running
+     * some time after that (live-confirmed: `msb ls` shows Running, and exec
+     * works, only once the restore process has already exited). A clean exit
+     * is therefore not itself a completed boot, and a nonzero exit is msb's
+     * own failure signal with the reason on stdout/stderr — the inverse of
+     * `run`'s attached child, whose exit before Running always means failure.
+     *
+     * Two phases follow directly from those two facts:
+     *   1. Spawn `msb restore ...` and wait for IT to exit, bounded by
+     *      `FIRST_RUN_PULL_TIMEOUT_MS` — the same boot budget `bootRunOnce`
+     *      polls against; a restore's own activation is exposed to the same
+     *      "this could be a slow cold operation" uncertainty a pull is.
+     *      Classified from the combined output the same way any boot's early
+     *      exit is (install-lock, state-db, image-cache-corruption,
+     *      port-bind-conflict — see `bootClassified`'s own doc on why a
+     *      restore boot needs the identical classification an ordinary one
+     *      gets) — a nonzero, unclassified exit throws an ordinary
+     *      `BackendError` carrying the output, same shape as `bootRunOnce`'s.
+     *   2. Once it exits 0, poll `msb ls` for the sandbox to reach Running —
+     *      the same `READINESS_POLL_MS` cadence and a fresh instance of the
+     *      identical `FIRST_RUN_PULL_TIMEOUT_MS` budget the attached path's
+     *      own poll uses (so a restore boot gets the identical readiness
+     *      patience an ordinary one does, counted from when there is
+     *      actually something to poll for rather than shaved out of phase
+     *      1's own budget). The sandbox settling on exactly `"Stopped"`, or
+     *      its name disappearing from a `msb ls` listing that itself came
+     *      back, is a definite failure the moment it is observed — never
+     *      worth waiting out the rest of the budget for, unlike a status
+     *      that simply hasn't reached Running yet.
+     *   3. The `ls` probe itself failing to run or return in time (spawn
+     *      error, or the same `LOGS_TIMEOUT_MS` `invoke` enforces on every
+     *      other probe) is a different thing entirely from the sandbox's name
+     *      being missing from a listing that DID come back, even though both
+     *      collapse to the same `undefined` once the probe's own promise is
+     *      caught — see `isCompletedFastExit`'s own doc, whose sibling
+     *      contract this mirrors: a probe failure must never be upgraded into
+     *      a false, specific diagnosis ("disappeared from msb ls entirely" is
+     *      exactly that kind of false claim when the truth is just that `ls`
+     *      itself didn't answer in time). A failed probe is therefore treated
+     *      as "not yet confirmed either way" and retried within budget —
+     *      install-lock races and an overloaded msb daemon are the same
+     *      transient shapes this file already documents for `run`/`restore`/
+     *      `stop`, and one `ls` hiccup during the readiness window must not
+     *      turn into a spurious restore failure.
+     *
+     * The `msb restore` CLI process itself is never held onto — it has already
+     * exited by the time phase 2 even starts, and msb itself (out-of-process)
+     * is the sandbox's own supervisor from here on, the same as it always was.
+     * But a restored sandbox reaches Running with ONLY its guest agent inside
+     * — the captured workload never re-executes on its own (EMPIRICALLY
+     * VERIFIED against msb 0.7.1) — so once Running is confirmed, this method
+     * calls `reviveWorkload` to start it itself BEFORE returning: THAT call is
+     * what populates `state.attached` (a workload-revival `msb exec` child,
+     * not the restore CLI process), and `stop()`'s ordinary attached-child
+     * handling (exit-based death detection, the SIGKILL escalation) applies to
+     * IT exactly as it always did for `bootRunOnce`'s own attached `msb run`
+     * child. See `reviveWorkload`'s own doc for the full revival contract,
+     * including the typed error a checkpoint predating workload-cmdline
+     * capture throws instead of booting silently idle.
+     *
+     * Phase 1 (spawning the restore itself and reading back its own exit code
+     * + combined output) is dispatched by `launchMode` to either
+     * `launchRestoreDirect` (the unconditional spawn this method has always
+     * used) or `launchRestoreViaBroker` (POLICY v2's Windows job-object
+     * escape hatch — see `RestoreLaunchMode`/`restore-broker.ts`'s own doc).
+     * Both return the exact same shape, classified identically right below —
+     * a brokered attempt's output goes through the SAME predicates
+     * (`isImageCacheCorruption`, `isRestoreAccessDeniedFailure`, ...) a direct
+     * attempt's always has, since the underlying `msb restore` invocation and
+     * its failure signatures are identical either way; only how its stdout/
+     * stderr and exit code got back to this process differs. A broker launch
+     * can also come back `"unconfirmed"` (its own `ecFile` never appeared
+     * within its bound) — see `RestoreBrokerUnconfirmed`'s own doc — which
+     * skips classification entirely and falls straight through to phase 2
+     * exactly as a confirmed exit 0 does, since that phase's own `msb ls` poll
+     * is activation-gated and settles the question on its own regardless.
+     */
+    async bootRestoreOnce(msbPath, handle, state, launchMode = "direct") {
+        const launch = launchMode === "broker"
+            ? await this.launchRestoreViaBroker(msbPath, handle, state)
+            : await this.launchRestoreDirect(msbPath, handle, state);
+        if (launch.kind === "completed") {
+            const { exitCode, output } = launch;
+            if (isImageCacheCorruption(output)) {
+                throw new ImageCacheCorruptionError(output);
+            }
+            if (isMsbStateDbError(output)) {
+                throw new StateDbError(output);
+            }
+            if (isMsbInstallLockActive(output)) {
+                throw new InstallLockActiveError(output);
+            }
+            if (isPortBindConflictOutput(output)) {
+                throw new PortBindConflictError(`msb restore for sandbox ${handle.id} could not bind a host port: ${output}`);
+            }
+            if (isRestoreAccessDeniedFailure(output)) {
+                throw new RestoreAccessDeniedError(output);
+            }
+            if (isSandboxAlreadyExistsFailure(output)) {
+                throw new SandboxAlreadyExistsError(output);
+            }
+            if (exitCode !== 0) {
+                throw new BackendError(`msb restore for sandbox ${handle.id} exited (code ${exitCode}) — check the snapshot ref and ` +
+                    `'msb restore' output below:\n${output}`);
+            }
+        }
+        // Exit 0 (direct or brokered), or the broker's own "unconfirmed" outcome
+        // — the restore CLI's own task is done, or close enough to trust `msb
+        // ls` to settle it (see this method's own doc) — poll for Running the
+        // same way bootRunOnce does, under a fresh instance of the identical
+        // budget.
+        const readyDeadline = Date.now() + FIRST_RUN_PULL_TIMEOUT_MS;
+        let lastSeenStatus;
+        for (;;) {
+            const ls = await invoke(msbPath, MsbCommands.ls(), LOGS_TIMEOUT_MS).catch(() => undefined);
+            // `ls === undefined` here means the probe itself never came back
+            // (spawn error, or its own LOGS_TIMEOUT_MS timing out) — a DIFFERENT
+            // thing from a returned listing that genuinely omits the sandbox's
+            // name (see this method's own doc, point 3, and `isCompletedFastExit`'s
+            // sibling doc). Only a listing that actually came back gets to update
+            // `lastSeenStatus` or trigger the Stopped/disappeared fast-fail below;
+            // a failed probe falls straight through to the readiness-budget check
+            // and is retried, never asserted as "the sandbox disappeared."
+            if (ls !== undefined) {
+                lastSeenStatus = statusOf(ls.stdout, handle.id);
+                if (lastSeenStatus === "Running") {
+                    // `msb restore` boots a restored sandbox with only its guest agent
+                    // inside — the captured workload never re-runs on its own (see
+                    // this method's own doc and `reviveWorkload`'s) — so this backend
+                    // starts it itself before registering the boot as complete. A
+                    // `reviveWorkload` failure propagates unclassified: never register
+                    // `startedNames` for a sandbox whose workload never actually came
+                    // up.
+                    await this.reviveWorkload(msbPath, handle, state);
+                    if (!handle.spec.keepAlive) {
+                        this.startedNames.add(handle.id);
+                    }
+                    return;
+                }
+                if (lastSeenStatus === "Stopped" || lastSeenStatus === undefined) {
+                    throw new BackendError(await this.restoreBootFailureMessage(msbPath, handle.id, lastSeenStatus, false));
+                }
+            }
+            if (Date.now() >= readyDeadline) {
+                throw new BackendError(await this.restoreBootFailureMessage(msbPath, handle.id, lastSeenStatus, true));
+            }
+            await sleep(READINESS_POLL_MS);
+        }
+    }
+    /**
+     * `bootRestoreOnce`'s own DIRECT launch — the unconditional child-process
+     * spawn every restore attempt used before POLICY v2's broker escalation
+     * existed, extracted unchanged from that method's own former body so the
+     * two `RestoreLaunchMode`s share one classification point (see
+     * `bootRestoreOnce`'s own doc). Bounded by the same `FIRST_RUN_PULL_TIMEOUT_MS`
+     * budget `bootRunOnce` polls against, and always resolves `"completed"` —
+     * a direct spawn has no analog of the broker's own `"unconfirmed"` outcome,
+     * since this process reads the child's real exit code directly.
+     */
+    async launchRestoreDirect(msbPath, handle, state) {
+        const argv = MsbCommands.restore(handle.spec);
+        const child = spawn(msbPath, argv, { stdio: [CLOSED_STDIN, "pipe", "pipe"] });
+        const stdoutDone = drainTail(child.stdout, state.logTail);
+        const stderrDone = drainTail(child.stderr, state.logTail);
+        const exitCode = await new Promise((resolveExit, rejectExit) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                child.kill("SIGKILL");
+                rejectExit(new BackendError(`msb restore for sandbox ${handle.id} did not exit within ${FIRST_RUN_PULL_TIMEOUT_MS / 1000}s — ` +
+                    `msb itself may be unresponsive; last output:\n${state.logTail.join("\n")}`));
+            }, FIRST_RUN_PULL_TIMEOUT_MS);
+            child.once("exit", (code) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                resolveExit(code ?? -1);
+            });
+        });
+        await Promise.all([stdoutDone, stderrDone]);
+        return { kind: "completed", exitCode, output: state.logTail.join("\n") };
+    }
+    /**
+     * `bootRestoreOnce`'s own BROKERED launch — POLICY v2's Windows job-object
+     * escape hatch (see `RestoreLaunchMode`/`restore-broker.ts`'s own module
+     * doc on the root cause and the live-validated WMI mitigation). Calls the
+     * injected `restoreBroker` seam with the exact same argv a direct attempt
+     * would spawn (`MsbCommands.restore`, unmodified) and the same
+     * `FIRST_RUN_PULL_TIMEOUT_MS` budget.
+     *
+     * The broker's own result is either passed straight through
+     * (`"completed"`/`"unconfirmed"`, both appended to `state.logTail` for the
+     * same pre-Running diagnostics purpose `drainTail` serves on the direct
+     * path) or, if the broker call itself REJECTS — broker infrastructure
+     * failing (a missing `powershell.exe`, a script-file write failure, WMI
+     * refusing to even create the process; see `RestoreBrokerLauncher`'s own
+     * doc on what counts as this vs. an ordinary brokered-restore failure) —
+     * caught here and turned into a one-attempt fallback to
+     * `launchRestoreDirect` instead (POLICY v2 point 5: the broker must never
+     * become a new single point of failure). That fallback is scoped to THIS
+     * attempt only; it does not touch the caller's own `RestoreLaunchMode` for
+     * whatever attempt comes after it.
+     */
+    async launchRestoreViaBroker(msbPath, handle, state) {
+        const argv = MsbCommands.restore(handle.spec);
+        let result;
+        try {
+            result = await this.restoreBroker(msbPath, argv, FIRST_RUN_PULL_TIMEOUT_MS);
+        }
+        catch (err) {
+            pushLinesToTail(state.logTail, `[restore broker] broker infrastructure failed for sandbox ${handle.id}, falling back to a direct ` +
+                `attempt: ${err instanceof Error ? err.message : String(err)}`);
+            return this.launchRestoreDirect(msbPath, handle, state);
+        }
+        if (result.kind === "unconfirmed") {
+            pushLinesToTail(state.logTail, `[restore broker] its own exit-code file never appeared within its wait bound for sandbox ` +
+                `${handle.id} — proceeding to the ls-poll phase rather than guessing an outcome.`);
+            return { kind: "unconfirmed" };
+        }
+        pushLinesToTail(state.logTail, result.output);
+        return { kind: "completed", exitCode: result.exitCode, output: result.output };
+    }
+    /**
+     * Renders a restore boot's post-mortem message once its poll for Running
+     * has definitely failed (a settled `"Stopped"`, the name disappearing
+     * from `msb ls` outright, or the readiness budget itself running out).
+     * `msb restore` itself already exited 0 by this point, so the CLI
+     * process's own output (already surfaced for a nonzero exit, above) has
+     * nothing left to add — `msb logs --source system` is the one channel
+     * that can still show what happened to the sandbox's own background boot
+     * (see `MsbCommands.systemLog`'s own doc and `isCompletedFastExit`, its
+     * other caller). Best-effort: a failed probe falls back to a plain "no
+     * output" note rather than letting a diagnostics-gathering failure itself
+     * throw and mask the real one.
+     */
+    async restoreBootFailureMessage(msbPath, id, status, timedOut) {
+        const systemLog = await invoke(msbPath, MsbCommands.systemLog(id), LOGS_TIMEOUT_MS).catch(() => undefined);
+        const diagnostics = systemLog !== undefined && systemLog.stdout.trim() !== ""
+            ? `'msb logs ${id} --source system' output:\n${systemLog.stdout}`
+            : `'msb logs ${id} --source system' produced no output`;
+        // `status` is the last CONFIRMED status a returned `msb ls` listing
+        // actually reported — never a value fabricated from a failed probe (see
+        // bootRestoreOnce's own doc, point 3): `undefined` here on the timedOut
+        // branch means every `ls` probe across the whole readiness budget failed
+        // to even come back, not that a listing came back without the name in
+        // it (that is the non-timedOut, "disappeared" branch below, which is
+        // only ever reached from a listing that DID come back).
+        const reason = timedOut
+            ? `did not reach Running within ${FIRST_RUN_PULL_TIMEOUT_MS / 1000}s of 'msb restore' exiting ` +
+                `(last confirmed status: ${status ?? "none — 'msb ls' never returned a usable listing"})`
+            : status === undefined
+                ? `disappeared from 'msb ls' entirely`
+                : `settled as '${status}' in 'msb ls'`;
+        return `sandbox ${id} was restored ('msb restore' exited 0) but ${reason} before ever reaching Running — ${diagnostics}`;
+    }
+    /**
+     * Starts the workload a restore itself never re-runs. EMPIRICALLY VERIFIED
+     * against msb 0.7.1: a restored sandbox reaches Running with ONLY its
+     * guest agent inside (`guest ps` shows `/init.krun` and kernel threads —
+     * the captured workload command does not re-execute; `msb start`/`msb
+     * logs` on such a sandbox are equally idle/empty). Only ever called from
+     * `bootRestoreOnce`, once it has confirmed Running — see this class's own
+     * doc on `bootRestoreOnce`.
+     *
+     * Spawns a LONG-LIVED, attached `msb exec [-e K=V]... <name> -- <argv>`
+     * session (`MsbCommands.execWithEnv`, env from `handle.spec.env` — a
+     * restore's own `msb restore` has no `-e`/`--env` flag at all, so this exec
+     * is the one place a restored sandbox's guest ever sees it again) — this
+     * becomes the sandbox's own workload from here on, and exec sessions are
+     * exactly what msb's own log capture records (the primary session's
+     * stdout/stderr land in `exec.log`, served by `msb logs`/`-f` — see
+     * `MsbCommands.exec`'s own doc). This exec child slots into the EXACT SAME
+     * `state.attached` role `bootRunOnce`'s own attached `msb run` child fills
+     * for an ordinary boot: child-exit-based death detection, reap-on-stop
+     * (`stop()`'s SIGKILL escalation), and every other attached-child teardown
+     * semantic apply to it unchanged — the detached-restore round left that
+     * slot merely optional, never removed it.
+     *
+     * `handle.spec.command` is ALREADY the fully-resolved workload argv by the
+     * time this runs, in priority order: an explicit command the source
+     * container carried, or — when it had none — the guest cmdline
+     * `createCheckpoint` captured at checkpoint time, merged in by
+     * `createCheckpoint` itself (for its own immediate reboot) or by
+     * `fromCheckpointRegistryEntry` (for a registry-mediated restore, same or
+     * later process — see both functions' own docs). `undefined` here means
+     * NEITHER source exists — an old registry entry predating capture, or one
+     * whose capture attempt itself failed — so this throws
+     * `CheckpointWorkloadCommandMissingError` itself rather than depending on
+     * a caller to have checked first: never boot a restored sandbox silently
+     * idle.
+     *
+     * The exec child gets a brief settle window (`EXEC_REVIVE_SETTLE_MS`) to
+     * prove it isn't an immediate boot failure before this returns success —
+     * mirroring `bootRunOnce`'s own exit-vs-Running race, except a restore's
+     * exec session has no separate "Running" signal of its own to poll for
+     * (the SANDBOX already reports Running regardless of whether this exec
+     * succeeds), so a settle window is what that race collapses to here. An
+     * exit observed within the window is classified exactly like
+     * `bootRunOnce`'s own early exit: exit 0 counts as success only when
+     * `isCompletedFastExit` ALSO confirms it (the sandbox itself settled
+     * Stopped with the boot-completion marker — the repo's existing fast-exit-
+     * completion semantics, reused verbatim); any other exit — nonzero, or
+     * exit 0 without that confirmation — throws a `BackendError` carrying the
+     * exec child's own output, the same failure shape an attached run's early
+     * exit already has.
+     */
+    async reviveWorkload(msbPath, handle, state) {
+        const command = handle.spec.command;
+        if (command === undefined) {
+            throw new CheckpointWorkloadCommandMissingError(handle.spec.checkpointRef ?? handle.id);
+        }
+        state.logTail = [];
+        const argv = MsbCommands.execWithEnv(handle.id, handle.spec.env, command);
+        const child = spawn(msbPath, argv, { stdio: [CLOSED_STDIN, "pipe", "pipe"] });
+        const stdoutDone = drainTail(child.stdout, state.logTail);
+        const stderrDone = drainTail(child.stderr, state.logTail);
+        let exited;
+        child.once("exit", (code) => {
+            exited = { code };
+            state.attachedExited = true;
+        });
+        const settleDeadline = Date.now() + EXEC_REVIVE_SETTLE_MS;
+        while (exited === undefined && Date.now() < settleDeadline) {
+            await sleep(READINESS_POLL_MS);
+        }
+        if (exited === undefined) {
+            // Stayed up through the whole settle window — the ordinary long-lived
+            // case. Slots into state.attached exactly like bootRunOnce's own
+            // attached child.
+            state.attached = child;
+            return;
+        }
+        await Promise.all([stdoutDone, stderrDone]);
+        const output = state.logTail.join("\n");
+        if (exited.code === 0 && (await this.isCompletedFastExit(msbPath, handle.id))) {
+            // Mirrors bootRunOnce's own fast-exit success case: the workload ran to
+            // completion so quickly this settle window caught its natural exit
+            // rather than a crash. No live child left to hold onto — state.attached
+            // stays undefined, same as bootRunOnce's own fast-exit branch.
+            return;
+        }
+        throw new BackendError(`msb exec for sandbox ${handle.id}'s revived workload exited (code ${exited.code ?? "unknown"}) before ` +
+            `staying up — check the workload command and its output below:\n${output}`);
+    }
+    /**
+     * Best-effort: execs `CAPTURE_WORKLOAD_CMDLINE_SCRIPT` in `handle`'s guest
+     * and parses its stdout via `parseCapturedWorkloadCmdline`. Only ever
+     * called from `createCheckpoint`, BEFORE it stops the sandbox (see that
+     * method's own doc), and only when `handle.spec.command` is undefined — an
+     * explicit command needs no capture. Never throws: an exec failure
+     * (nonzero exit, the exec channel itself erroring) and unparseable output
+     * both resolve `undefined` rather than failing the checkpoint — the
+     * captured cmdline is a best-effort fallback, and its absence is fully
+     * handled later, at restore time (`reviveWorkload` throws
+     * `CheckpointWorkloadCommandMissingError` when neither an explicit nor a
+     * captured command exists).
+     */
+    async captureGuestWorkloadCmdline(handle) {
+        try {
+            const result = await this.exec(handle, ["sh", "-c", CAPTURE_WORKLOAD_CMDLINE_SCRIPT]);
+            if (result.exitCode !== 0) {
+                return undefined;
+            }
+            return parseCapturedWorkloadCmdline(result.stdout);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * SPI implementation of `SandboxBackend.capturedWorkloadCommand` — see its
+     * own doc. Reads back whatever `createCheckpoint` most recently stashed on
+     * this sandbox's `HandleState` (keyed by name, so it survives the
+     * stop/snapshot/reboot cycle's own handle-object churn); `undefined` if
+     * this sandbox was never checkpointed, or its checkpoint needed no
+     * capture, or the capture attempt failed.
+     */
+    capturedWorkloadCommand(handle) {
+        return this.handles.get(handle.id)?.capturedCommand;
+    }
     /**
      * The fast-exit post-mortem classification: only ever consulted from
-     * `bootOnce` above, and only once the attached `msb run` child has already
+     * `bootRunOnce` above, and only once the attached `msb run` child has already
      * exited with code 0 before Running was observed. msb 0.6.16's
      * convergent-lifecycle rework means a workload that finishes quickly is
      * never observed `"Running"` at all — only `"Starting"`, then the attached
@@ -543,11 +1231,16 @@ export class MsbCliBackend {
         }
         await invoke(msbPath, MsbCommands.stop(handle.id), STOP_TIMEOUT_MS).catch(() => { });
         const attached = state?.attached;
-        // The attached `msb run` child is msb's own supervisor for this sandbox:
-        // it stays alive for the sandbox's entire lifetime and only exits once
-        // the `msb stop` call just above lands, so the common path here is
-        // "attach a listener, then observe the exit that our own stop just
-        // caused." state.attachedExited exists for the other case: if the child
+        // The attached child is either an ordinary boot's `msb run` process —
+        // msb's own supervisor for this sandbox, staying alive for its entire
+        // lifetime — or, for a restored sandbox, the `msb exec` session
+        // `reviveWorkload` spawned to revive its captured workload (msb itself,
+        // out-of-process, is the actual supervisor there; this exec child is
+        // just the workload session riding inside it). Either way it stays alive
+        // until the sandbox itself stops, and only exits once the `msb stop`
+        // call just above lands, so the common path here is "attach a listener,
+        // then observe the exit that our own stop just caused." state.attachedExited
+        // exists for the other case: if the child
         // had already died before this method ever ran (crashed, or killed by
         // something external), start()'s own listener already flipped it, and
         // Node never replays a past "exit" event to a listener attached after
@@ -586,30 +1279,340 @@ export class MsbCliBackend {
         this.startedNames.delete(handle.id);
         this.handles.delete(handle.id);
     }
+    /**
+     * `bootClassified`'s own retry for a `RestoreAccessDeniedError` hit on the
+     * ordinary `start()`/`fromCheckpoint().start()` path (its default
+     * `retryAccessDenied: true`) — the sibling of `rebootUnderFreshName`
+     * (`createCheckpoint`'s own reboot retry) for the SAME classified failure,
+     * built from the SAME live-verified policy: `msb restore --name X`
+     * validates the artifact FIRST — an integrity failure exits 1 and leaves
+     * NO sandbox record — but a failure AFTER validation (this access-denied
+     * signature included) leaves `X` behind as a STOPPED SANDBOX RECORD, and
+     * any retry of `restore --name X` then fails outright with msb's own
+     * "already exists" refusal rather than hitting the transient a second
+     * time. A same-name retry (what this method replaces) therefore only ever
+     * proves that collision — never the actual transient — so this mints a
+     * NEW name from `nextSandboxName()` for every retry instead, the same
+     * generator `GenericContainer.start()`'s own boot loop and
+     * `rebootUnderFreshName` both use, tracking it in the reaper ledger BEFORE
+     * that attempt's restore runs and best-effort `msb rm`-ing (then
+     * untracking) a failed attempt's own name before advancing — identical
+     * per-attempt bookkeeping to `rebootUnderFreshName`, just owned one layer
+     * lower.
+     *
+     * The difference from `rebootUnderFreshName` is entirely about WHO owns
+     * the re-keying, not the retry policy itself: `createCheckpoint` calls
+     * `rebootUnderFreshName` with no live sandbox left at all (the source was
+     * already stopped and removed as part of the snapshot step), so EVERY
+     * attempt — including the first — mints a fresh name, and the winning
+     * handle is handed back for `createCheckpoint` itself to re-key. Here,
+     * `handle` is already live under its own name when `first` (the initial
+     * `RestoreAccessDeniedError`) is caught, and `bootClassified`'s caller
+     * (`start()`) has no re-keying step of its own — it just awaits
+     * `bootClassified` and returns — so this method re-keys
+     * `this.handles`/`this.startedNames` AND mutates the caller's own `handle`
+     * object IN PLACE itself on success, the same "one carve-out"
+     * `SandboxHandle`'s own interface doc allows for `createCheckpoint`'s
+     * reboot (see that method's own doc on `handle.id`/`handle.spec`
+     * mutation).
+     *
+     * `handle`'s own original name was already tracked in the reaper ledger by
+     * `GenericContainer.start()`'s own boot loop before `create()`/`start()`
+     * ever ran (mirroring `rebootUnderFreshName`'s treatment of the checkpoint
+     * reboot's own `originalName`) — this method best-effort `msb rm`'s it
+     * once `first` is confirmed retryable, but deliberately leaves its own
+     * ledger entry alone, for the same not-found-tolerant sweep to find,
+     * rather than untracking a name this method never tracked itself.
+     *
+     * Retries up to `RESTORE_ACCESS_DENIED_RETRY_LIMIT` times,
+     * `RESTORE_ACCESS_DENIED_RETRY_DELAY_MS` apart — unchanged from the
+     * same-name retry this replaces. Each attempt goes through
+     * `bootClassified` itself with `retryAccessDenied: false` (so a
+     * `StateDbError`/`InstallLockActiveError`/`ImageCacheCorruptionError` hit
+     * mid-retry still gets its own ordinary classified handling; only
+     * `RestoreAccessDeniedError`'s own retry is owned here) and treats either
+     * `RestoreAccessDeniedError` or `SandboxAlreadyExistsError` as retryable —
+     * a freshly minted name should never collide, but `rebootUnderFreshName`'s
+     * own live-CI evidence says a loaded host can still refuse one, and the
+     * SAME fresh-naming response (rm the failed name, mint another) covers
+     * both signatures identically. Anything else propagates immediately,
+     * unretried.
+     *
+     * POLICY v2's broker escalation applies here too, on the exact same terms
+     * as `rebootUnderFreshName`'s own (see that method's own doc): this
+     * method is only ever entered once the reboot's first, always-direct
+     * attempt has already hit `RestoreAccessDeniedError` (`first`), so on a
+     * Windows host (`isWindowsPlatform()`) every retry THIS method itself
+     * performs is, by construction, an attempt after that trigger — there is
+     * no "first attempt still direct" sub-case to preserve inside this loop
+     * the way `rebootUnderFreshName` has to across its own. `launchMode` is
+     * therefore decided once, before the loop, not re-evaluated per attempt.
+     */
+    async retryRestoreAfterAccessDenied(msbPath, handle, state, first) {
+        const originalName = handle.id;
+        // Best-effort: `first` may have left a stopped sandbox record behind
+        // under `originalName` (see this method's own doc) — cheap cleanup, and
+        // correctness never depends on it, since no retry below ever reuses this
+        // name. Its own ledger entry is deliberately left alone; see this
+        // method's own doc.
+        await invoke(msbPath, MsbCommands.rm(originalName), STOP_TIMEOUT_MS).catch(() => { });
+        const launchMode = this.isWindowsPlatform() ? "broker" : "direct";
+        let last = first;
+        for (let attempt = 1; attempt <= RESTORE_ACCESS_DENIED_RETRY_LIMIT; attempt++) {
+            await sleep(RESTORE_ACCESS_DENIED_RETRY_DELAY_MS);
+            const name = nextSandboxName();
+            if (!handle.spec.keepAlive) {
+                await trackSandbox(name);
+            }
+            const candidate = { id: name, spec: { ...handle.spec, name } };
+            try {
+                await this.bootClassified(msbPath, candidate, state, { retryAccessDenied: false, restoreLaunchMode: launchMode });
+                // Success under `name` — re-key this backend's own runtime
+                // registries (see class doc on `handles`) and publish the new
+                // identity onto the CALLER's own handle object, IN PLACE, exactly
+                // like `createCheckpoint`'s own reboot does (see its own doc).
+                this.handles.delete(originalName);
+                this.handles.set(name, state);
+                this.startedNames.delete(originalName);
+                const mutableHandle = handle;
+                mutableHandle.id = name;
+                mutableHandle.spec = candidate.spec;
+                return;
+            }
+            catch (err) {
+                const classified = err instanceof RestoreAccessDeniedError || err instanceof SandboxAlreadyExistsError;
+                if (!classified) {
+                    if (!handle.spec.keepAlive) {
+                        await untrackSandbox(name);
+                    }
+                    throw err;
+                }
+                // Best-effort, result ignored either way — see this method's own
+                // doc on why correctness no longer depends on it.
+                await invoke(msbPath, MsbCommands.rm(name), STOP_TIMEOUT_MS).catch(() => { });
+                if (!handle.spec.keepAlive) {
+                    await untrackSandbox(name);
+                }
+                last = err;
+            }
+        }
+        throw new BackendError(`msb restore for sandbox ${originalName} kept hitting msb's Windows access-denied/"sandbox already ` +
+            `exists" refusal across ${RESTORE_ACCESS_DENIED_RETRY_LIMIT} retries, each under a freshly minted ` +
+            `name — this is normally a brief file-handle release lag that clears within one retry, so a failure ` +
+            `held this long looks like a genuinely stuck lock on this host.\n${last.output}`);
+    }
+    /**
+     * `createCheckpoint`'s own reboot step. Mints a NEW sandbox name from
+     * `nextSandboxName()` (the same generator `GenericContainer.start()`'s own
+     * boot loop uses) for EVERY attempt, tracks it in the reaper ledger BEFORE
+     * that attempt's restore runs (mirroring `GenericContainer.start()`'s own
+     * `trackSandbox` call, keepAlive-excluded the same way), and retries two
+     * classified failure signatures on that basis instead of surfacing either
+     * immediately: msb's "sandbox already exists" refusal
+     * (`SandboxAlreadyExistsError`, see `isSandboxAlreadyExistsFailure`'s own
+     * doc) and its Windows access-denied refusal on the just-written snapshot
+     * artifact (`RestoreAccessDeniedError`, see `isRestoreAccessDeniedFailure`'s
+     * own doc — retried here rather than inside `bootClassified` itself, via
+     * that method's own `retryAccessDenied: false`, see its doc).
+     *
+     * LIVE-VERIFIED POLICY this retry is built from: `msb restore --name X`
+     * validates the artifact FIRST — an integrity failure exits 1 and leaves NO
+     * sandbox record — but a failure AFTER validation (a block-device open
+     * PermissionDenied on unix; `RestoreAccessDeniedError`'s own signature on
+     * Windows) leaves `X` behind as a STOPPED SANDBOX RECORD visible in `msb
+     * ls`, and any retry of `restore --name X` then fails with msb's own
+     * "already exists" refusal — so a same-name retry of EITHER classified
+     * failure only ever collides with itself. Reusing a failed attempt's name
+     * is therefore never safe (`msb rm` alone is not reliably enough either: on
+     * Windows it frees only the DB record, not the on-disk directory, which can
+     * outlive it well past this budget — see the fresh-name reboot's own doc on
+     * `createCheckpoint`) — the only universally safe policy is a NEW name per
+     * attempt, same as this backend's ordinary `start()` boot loop already uses
+     * for its own, unrelated port-conflict retries. On a classified failure
+     * this best-effort `msb rm`'s the failed attempt's own name anyway (result
+     * ignored — cheap cleanup, and correctness no longer depends on it now
+     * that the next attempt never reuses that name) and untracks it from the
+     * ledger, before advancing to a freshly minted name for the next attempt.
+     *
+     * `this.checkpointRebootAlreadyExistsRetryBudgetMs`/`_RetryDelayMs` back
+     * this loop's overall deadline/delay rather than the bare
+     * `CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_BUDGET_MS`/`_DELAY_MS` constants
+     * directly, so a budget-exhaustion test can shrink them to milliseconds
+     * instead of actually blocking for the real ~30s — see those fields' own
+     * doc. Only `SandboxAlreadyExistsError`/`RestoreAccessDeniedError` are
+     * retried here; any other failure `bootClassified` throws (on the first
+     * attempt or a later one) propagates immediately, unretried, WITHOUT
+     * advancing to a new name — `createCheckpoint`'s own caller untracks that
+     * attempt's name on this path (see its own catch block). Not reached by
+     * the ordinary `start()` path: a `GenericContainer.fromCheckpoint(cp)
+     * .start()` restore's own `RestoreAccessDeniedError` is retried by its own
+     * sibling, `retryRestoreAfterAccessDenied` (see that method's own doc) —
+     * same fresh-naming policy, applied one layer lower since that path has no
+     * separate caller left to hand a replacement handle to for re-keying.
+     *
+     * Returns the WINNING attempt's own `SandboxHandle` (a fresh object, never
+     * `undefined`) — `createCheckpoint` re-keys its runtime registries and the
+     * caller's live handle from this, not from a name minted up front.
+     *
+     * POLICY v2's broker escalation (see `RestoreLaunchMode`/`restore-broker.ts`'s
+     * own module doc on the Windows job-object root cause and the live-
+     * validated WMI mitigation) lives here: `launchMode` starts `"direct"` —
+     * the first attempt of ANY reboot is always a direct spawn, unconditionally,
+     * even on Windows — and flips to `"broker"` the moment an attempt hits
+     * `RestoreAccessDeniedError` on a Windows host (`isWindowsPlatform()`);
+     * every attempt from then on, for the rest of THIS reboot, launches
+     * brokered instead, never downgrading back to direct even if a later
+     * attempt's own failure is only `SandboxAlreadyExistsError` (still
+     * retried, but no longer the trigger — only access-denied escalates).
+     * Off Windows, `launchMode` never leaves `"direct"` at all — this reboot's
+     * whole retry loop behaves exactly as it did before this policy existed.
+     */
+    async rebootUnderFreshName(msbPath, sourceSpec, effectiveRef, capturedCommand, state) {
+        const deadline = Date.now() + this.checkpointRebootAlreadyExistsRetryBudgetMs;
+        let attempt = 0;
+        let last;
+        let launchMode = "direct";
+        for (;;) {
+            attempt += 1;
+            const name = nextSandboxName();
+            if (!sourceSpec.keepAlive) {
+                await trackSandbox(name);
+            }
+            const rebootHandle = {
+                id: name,
+                spec: { ...sourceSpec, name, checkpointRef: effectiveRef, command: sourceSpec.command ?? capturedCommand },
+            };
+            try {
+                await this.bootClassified(msbPath, rebootHandle, state, { retryAccessDenied: false, restoreLaunchMode: launchMode });
+                return rebootHandle;
+            }
+            catch (err) {
+                const classified = err instanceof SandboxAlreadyExistsError || err instanceof RestoreAccessDeniedError;
+                if (!classified) {
+                    if (!sourceSpec.keepAlive) {
+                        await untrackSandbox(name);
+                    }
+                    throw err;
+                }
+                if (err instanceof RestoreAccessDeniedError && this.isWindowsPlatform()) {
+                    // POLICY v2: escalate for every remaining attempt of this reboot —
+                    // see this method's own doc on `launchMode`.
+                    launchMode = "broker";
+                }
+                // Best-effort: ignore the result either way — a "not found" is as
+                // fine as an actual removal, and this is cleanup, not something the
+                // next attempt (a brand-new name) depends on for correctness.
+                await invoke(msbPath, MsbCommands.rm(name), STOP_TIMEOUT_MS).catch(() => { });
+                if (!sourceSpec.keepAlive) {
+                    await untrackSandbox(name);
+                }
+                last = err;
+                if (Date.now() >= deadline) {
+                    throw new BackendError(`msb restore kept hitting msb's "sandbox already exists"/access-denied refusal for ` +
+                        `${this.checkpointRebootAlreadyExistsRetryBudgetMs / 1000}s across ${attempt} attempt` +
+                        `${attempt === 1 ? "" : "s"}, each under a freshly minted name — msb's own on-disk sandbox ` +
+                        `directory can lag its database record's own release on a loaded Windows host well past a short ` +
+                        `wait, but a refusal held this long looks like a genuinely stuck host rather than a release ` +
+                        `race.\nlast attempt ('${name}'):\n${last.output}`);
+                }
+                await sleep(this.checkpointRebootAlreadyExistsRetryDelayMs);
+            }
+        }
+    }
     /**
      * The stop/snapshot/reboot cycle: `msb stop <name>` (reusing this
      * backend's own `stop()`, which also quiesces the attached child and any
-     * network-link tunnels), `msb snapshot create --from <name> <ref>`, then
-     * `msb rm <name>` followed by a fresh ATTACHED boot of the SAME name from
-     * that snapshot — never `msb start`. Upstream's detached-start path
-     * (`Sandbox::start_detached`) passes `CREATE_BREAKAWAY_FROM_JOB` on
-     * Windows, which `ERROR_ACCESS_DENIED`s outright whenever the msb CLI runs
-     * inside a job object that doesn't grant breakaway rights — a Gradle/
-     * cargo/node test runner on a hosted Windows runner, or any process that
-     * embeds this library inside its own restrictive job object — and that
-     * denial is deterministic, not transient, so no retry shape fixes it.
-     * Attached `msb run` (this backend's normal boot, including `--from-snapshot`
-     * boots) never hits it, which is why the reboot reuses `bootOnce` instead
-     * of resuming in place: the stopped sandbox's disk state is already IN the
-     * snapshot, so `rm`-ing it first and booting a fresh attached sandbox
-     * under the same name/ports/env/memory (via a spec identical to
-     * `handle.spec` except `checkpointRef` set to the new `ref`) reproduces
-     * the exact same observable contract. `bootOnce` swaps `state.attached` to
-     * the freshly spawned child itself; nothing about `this.handles`/
-     * `startedNames` or the reaping ledger changes, since the name never
-     * changed. Its workload restarts from scratch (the VM reboots), which is
-     * why `capabilities.checkpointRestartsWorkload` is `true` here and the
-     * generic layer re-runs the wait strategy after this returns.
+     * network-link tunnels), `msb snapshot create --from-sandbox <name> <ref>`
+     * (whose printed artifact path — never `ref` itself — becomes the
+     * EFFECTIVE checkpoint ref this method returns; see
+     * `parseSnapshotCreateArtifactPath`), then `msb rm <name>` followed by
+     * `msb restore <effective-ref> --name <fresh-name>` of a FRESH name from
+     * that snapshot (via `rebootUnderFreshName`/`bootRestoreOnce`, see
+     * `MsbCommands.restore`'s own doc — no `--disk-only`, which a disk-scope
+     * snapshot rejects) — never `msb start`. The fresh name — never the
+     * original — is minted by `nextSandboxName()` (the same generator
+     * `GenericContainer.start()`'s own ordinary boot loop uses; see
+     * `core/sandbox-name.ts`), and a NEW one is minted for EVERY attempt, never
+     * just once for the whole reboot: EMPIRICALLY VERIFIED against a real msb
+     * 0.7.1 binary, a restore that fails PAST msb's own artifact validation
+     * (its Windows access-denied signature, `RestoreAccessDeniedError`) leaves
+     * its `--name` behind as a STOPPED SANDBOX RECORD, and any retry under that
+     * SAME name then collides with msb's own restore-time collision check
+     * (`existing.is_some() || dir_exists`) immediately — CONFIRMED on Windows
+     * CI, where five checkpoint tests collided on their fresh reboot names for
+     * the retry loop's ENTIRE budget once the first attempt hit that
+     * access-denied failure (see `CHECKPOINT_REBOOT_ALREADY_EXISTS_RETRY_BUDGET_MS`'s
+     * own doc). A same-name retry therefore only ever retries through a race of
+     * its own making; a NEW name per attempt sidesteps it structurally — a name
+     * nothing else has ever used can never collide with a record or a lingering
+     * directory left by a name nothing will ever restore under again (see
+     * `rebootUnderFreshName`'s own doc for the full retry policy, including its
+     * best-effort `msb rm` of each failed attempt's own name). On success, this method
+     * mutates `handle.id` and `handle.spec` (name only — see below) IN PLACE
+     * on the caller's own `handle`, so every subsequent operation against it
+     * (exec/logs/stop/rm, and — one layer up, via the SAME `SandboxHandle`
+     * reference — `GenericContainer.checkpoint()`'s own post-reboot
+     * `installNetworkLinks`/wait-strategy re-run and `capturedWorkloadCommand()`
+     * call) targets the sandbox actually running now. `SandboxBackend`'s own
+     * interface doc calls `SandboxHandle` "immutable" — this is the one
+     * carve-out, and only this method makes it: a checkpoint reboot is the one
+     * operation that changes what sandbox a handle even refers to. `ports`,
+     * `env`, and `memoryLimitMb` are untouched by the rename — same ports, env,
+     * and memory ceiling as before the reboot, only the name differs.
+     * Upstream's
+     * detached-start path (`Sandbox::start_detached`) passes
+     * `CREATE_BREAKAWAY_FROM_JOB` on Windows, which `ERROR_ACCESS_DENIED`s
+     * outright whenever the msb CLI runs inside a job object that doesn't
+     * grant breakaway rights — a Gradle/cargo/node test runner on a hosted
+     * Windows runner, or any process that embeds this library inside its own
+     * restrictive job object — and that denial is deterministic, not
+     * transient, so no retry shape fixes it. Before 0.7.1, attached `msb run`
+     * (including its `--from-snapshot` boots) never hit this, which is why the
+     * reboot has always gone through the classified boot path (`bootClassified`)
+     * rather than `msb start`. `msb restore` has no attached/detached
+     * distinction of its own — its CLI process always calls `sandbox.detach()`
+     * internally and exits once activation is confirmed (see
+     * `bootRestoreOnce`'s own doc on why its exit is a SUCCESS signal, not
+     * something to reap) — so whether it shares upstream's
+     * `CREATE_BREAKAWAY_FROM_JOB` path on Windows is NOT verified here: this
+     * backend never runs the real msb binary (see this repo's hard "never boot
+     * a sandbox" rule), so this is a real open question for CI, not something
+     * this migration could confirm either way. If it recurs, it will surface
+     * as an ordinary unclassified `BackendError` out of `bootRestoreOnce`
+     * (deterministic exit-code failure, not one of the classified transients
+     * above), the same shape a genuine breakaway denial always took.
+     * `rm`-ing the sandbox first and restoring a fresh one under a fresh
+     * name, same ports/memory (via a spec identical to `handle.spec` except
+     * `name`/`checkpointRef` set to the fresh name and the EFFECTIVE ref this
+     * method discovers, below — env is no longer threaded through at all, see
+     * `MsbCommands.restore`) reproduces the exact same observable contract
+     * MODULO the name itself, which was always an implementation detail, not
+     * part of what a checkpoint promises to preserve. This backend's own
+     * `handles`/`startedNames` registries ARE re-keyed from the original name
+     * to the WINNING attempt's name (see below), and each attempt's own fresh
+     * name is tracked in the reaping ledger before that attempt's restore is
+     * even attempted, exactly like an ordinary `create()` — a failed attempt's
+     * name is untracked again by `rebootUnderFreshName` itself, while the
+     * original name's own ledger entry is deliberately left alone throughout,
+     * for the ledger's existing not-found-tolerant sweep to find (it was
+     * already `msb rm`-ed above). Its workload restarts from scratch (the VM
+     * reboots), which is why `capabilities.checkpointRestartsWorkload` is
+     * `true` here and the generic layer re-runs the wait strategy after this
+     * returns — AFTER `bootRestoreOnce` has already revived the workload
+     * itself via `reviveWorkload` (see that method's own doc): `msb restore`
+     * boots the reboot idle, only the guest agent inside, so `bootRestoreOnce`
+     * no longer leaves `state.attached` untouched the way it did before this
+     * revival step existed — it now carries the workload-revival exec child,
+     * the same attached-child slot `bootRunOnce`'s own `msb run` child fills
+     * for an ordinary boot.
+     *
+     * Before stopping the source sandbox, this also best-effort captures its
+     * guest workload cmdline (`captureGuestWorkloadCmdline`) when
+     * `handle.spec.command` is undefined — the image's own default entrypoint
+     * was running, so there is no explicit command for `reviveWorkload` to
+     * fall back on at either this method's own immediate reboot or a later,
+     * registry-mediated restore. See that method's own doc for why a capture
+     * failure never fails the checkpoint itself.
      *
      * If the snapshot step fails, the sandbox is left stopped — no
      * best-effort restart, since that restart would itself be the broken `msb
@@ -621,6 +1624,22 @@ export class MsbCliBackend {
      *
      * Refuses outright, before any of the above, when `handle.spec.tmpfsRootMb`
      * is set: a tmpfs root has nothing on disk for a snapshot to capture.
+     *
+     * `ref` is the WORKING ref this method is asked to checkpoint under — its
+     * basename becomes the snapshot create call's `<name>` argument (still
+     * meaningful: it lands in msb's own index, see `MsbCommands.snapshotCreate`'s
+     * own doc) and, for a path ref, its dirname becomes `--dest-dir`. It is
+     * NOT necessarily where the artifact ends up: EMPIRICALLY VERIFIED against
+     * a real msb 0.7.1 binary, `snapshot create` always writes under
+     * `<destDir-or-default>/<sandbox>/snap_<32-hex-digest>`, a path `name`
+     * never determines. This method therefore parses that real artifact path
+     * back out of the command's own stdout (last non-empty line, required to
+     * be absolute — see `parseSnapshotCreateArtifactPath`) and returns THAT as
+     * the EFFECTIVE ref — the one used for the reboot below and the one the
+     * caller (`GenericContainer.checkpoint()`) stores in the registry and
+     * hands back on the `Checkpoint` it returns. Malformed or unrecognizable
+     * output (empty, no absolute last line) throws a `BackendError` quoting
+     * the raw, unparsed output verbatim rather than guessing a ref.
      */
     async createCheckpoint(handle, ref) {
         if (handle.spec.tmpfsRootMb !== undefined) {
@@ -630,58 +1649,146 @@ export class MsbCliBackend {
             throw new TmpfsRootCheckpointError();
         }
         const msbPath = await this.msbPath();
+        // Captured up front: `handle.id` itself is mutated in place, below, once
+        // the reboot under the fresh name has actually succeeded — every
+        // reference to the SOURCE sandbox's own name in this method (the
+        // stop/snapshot/rm steps, the pre-mutation error messages) goes through
+        // this local instead, never `handle.id` directly, so it stays correct
+        // regardless of when that mutation happens.
+        const originalName = handle.id;
+        const state = this.handles.get(originalName);
+        if (state === undefined) {
+            throw new BackendError(`no handle state for sandbox '${originalName}' — create() was never called for it`);
+        }
+        // Guest cmdline capture — BEFORE stopping the source sandbox (see
+        // captureGuestWorkloadCmdline's own doc) — only when there is no
+        // explicit command for a restore to fall back on later. Best-effort: a
+        // capture failure never fails the checkpoint itself (captureGuestWorkloadCmdline
+        // already swallows it into `undefined`); its absence only surfaces
+        // later, at restore time, as CheckpointWorkloadCommandMissingError.
+        // Stashed on `state` (kept by reference across this method's own
+        // re-keying below, so it survives the remove+reboot churn) for
+        // `capturedWorkloadCommand()` to hand back to `GenericContainer.checkpoint()`
+        // afterward.
+        const capturedCommand = handle.spec.command === undefined ? await this.captureGuestWorkloadCmdline(handle) : undefined;
+        state.capturedCommand = capturedCommand;
         await this.stop(handle);
-        // A path ref (see checkpoint/ref.ts) stores its artifact under the ref
-        // itself: mkdirs the parent, then hands msb the ref's own basename as
-        // the snapshot name and the parent as --dest-dir, so the artifact msb
-        // writes lands at exactly <parent>/<basename> === ref. A bare-name ref
-        // (pre-dest-dir checkpoints, still restorable) keeps going through
-        // msb's own default snapshot store, unchanged.
+        // A path ref (see checkpoint/ref.ts) hands msb the ref's own basename as
+        // the snapshot NAME and the parent as --dest-dir — the parent directory
+        // is honored, but (since msb 0.7.1) the artifact itself lands nested
+        // under <parent>/<sandbox>/snap_<digest>, never literally at `ref`; see
+        // this method's own doc. A bare-name ref (pre-dest-dir checkpoints,
+        // still restorable) keeps going through msb's own default snapshot
+        // store, unchanged.
         const isPathRef = path.isAbsolute(ref);
         if (isPathRef) {
             await fs.mkdir(path.dirname(ref), { recursive: true });
         }
         const snapshotArgv = isPathRef
-            ? MsbCommands.snapshotCreate(handle.id, path.basename(ref), path.dirname(ref))
-            : MsbCommands.snapshotCreate(handle.id, ref);
+            ? MsbCommands.snapshotCreate(originalName, path.basename(ref), path.dirname(ref))
+            : MsbCommands.snapshotCreate(originalName, ref);
         const snap = await invoke(msbPath, snapshotArgv, CHECKPOINT_TIMEOUT_MS);
         if (snap.exitCode !== 0) {
-            throw new BackendError(`msb snapshot create --from ${handle.id} ${ref} failed (exit ${snap.exitCode}): ${snap.stderr.trim()} — ` +
-                `the sandbox is left stopped; run 'msb start ${handle.id}' by hand to bring it back up.`);
+            throw new BackendError(`msb snapshot create --from ${originalName} ${ref} failed (exit ${snap.exitCode}): ${snap.stderr.trim()} — ` +
+                `the sandbox is left stopped; run 'msb start ${originalName}' by hand to bring it back up.`);
         }
-        await invoke(msbPath, MsbCommands.rm(handle.id), STOP_TIMEOUT_MS).catch(() => { });
-        const state = this.handles.get(handle.id);
-        if (state === undefined) {
-            throw new BackendError(`no handle state for sandbox '${handle.id}' — create() was never called for it`);
+        const effectiveRef = parseSnapshotCreateArtifactPath(snap.stdout);
+        if (effectiveRef === undefined) {
+            throw new BackendError(`msb snapshot create --from ${originalName} ${ref} did not print a recognizable artifact path as its ` +
+                `last line — the sandbox is left stopped; run 'msb start ${originalName}' by hand to bring it back up. ` +
+                `Raw output:\n${snap.stdout}${snap.stderr}`);
         }
-        const rebootHandle = { id: handle.id, spec: { ...handle.spec, checkpointRef: ref } };
+        await invoke(msbPath, MsbCommands.rm(originalName), STOP_TIMEOUT_MS).catch(() => { });
+        // `command` resolves the same way `fromCheckpointRegistryEntry` resolves
+        // it for a later, registry-mediated restore: the source's own explicit
+        // command first, the guest cmdline just captured above as the fallback —
+        // so `reviveWorkload`, inside the reboot this triggers next, already has
+        // the fully-resolved workload argv without any restore-time lookup. This
+        // merged `command` (and `checkpointRef`) live ONLY on each attempt's own
+        // handle inside `rebootUnderFreshName`, never on the caller's own
+        // `handle.spec` (mutated below) — that spec must keep reading back
+        // exactly what the SOURCE container's own `spec.command` was (`undefined`
+        // when there was none), since `GenericContainer.checkpoint()` reads
+        // `handle.spec` again right after this returns to build the
+        // named-checkpoint registry entry, which pins that same "explicit
+        // command vs. captured fallback" distinction as two separate fields (see
+        // `CheckpointRegistryEntry`'s own doc).
+        //
+        // `rebootUnderFreshName` owns minting a NEW name per attempt (never
+        // `originalName`, never a prior failed attempt's own name), tracking each
+        // one in the reaping ledger before that attempt's restore runs, and —
+        // per attempt — best-effort `msb rm`-ing and untracking a failed name
+        // before advancing to another fresh one (see that method's own doc for
+        // the full policy). `originalName`'s own ledger entry is deliberately
+        // left alone throughout: it was already `msb rm`-ed above, and the
+        // ledger's sweep is already not-found-tolerant for exactly this shape (a
+        // name the ledger still lists but msb itself has no record of).
+        let rebootHandle;
         try {
-            await this.bootClassified(msbPath, rebootHandle, state);
+            rebootHandle = await this.rebootUnderFreshName(msbPath, handle.spec, effectiveRef, capturedCommand, state);
         }
         catch (err) {
             const detail = err instanceof Error ? err.message : String(err);
-            throw new BackendError(`sandbox '${handle.id}' was removed after a successful checkpoint snapshot, but booting a fresh ` +
+            throw new BackendError(`sandbox '${originalName}' was removed after a successful checkpoint snapshot, but booting a fresh ` +
                 `sandbox back up from that snapshot failed: ${detail} — the sandbox's disk state is preserved in ` +
-                `checkpoint '${ref}', restorable via GenericContainer.fromCheckpoint().`);
+                `checkpoint '${effectiveRef}', restorable via GenericContainer.fromCheckpoint().`);
         }
+        const freshName = rebootHandle.id;
+        // The reboot succeeded under `freshName` — the WINNING attempt's own
+        // name, not `originalName` — re-key this backend's own runtime
+        // registries (see class doc on `handles`), then publish the new identity
+        // onto the CALLER's own handle object, IN PLACE, so every subsequent
+        // operation on it targets the sandbox actually running now (see this
+        // method's own doc). Only `id`/`spec.name` change on the live handle —
+        // `spec.command`/`spec.checkpointRef` stay exactly as they were on the
+        // SOURCE spec; see the comment above for why.
+        this.handles.delete(originalName);
+        this.handles.set(freshName, state);
+        this.startedNames.delete(originalName);
+        const mutableHandle = handle;
+        mutableHandle.id = freshName;
+        mutableHandle.spec = { ...handle.spec, name: freshName };
+        return effectiveRef;
     }
     /**
-     * Best-effort `msb snapshot rm <basename(ref)>` — "not found" is success,
-     * the same contract as `removeByName`. msb's own removal deletes both its
-     * index entry and the dest-dir artifact for a path ref, but afterwards this
-     * also best-effort recursively deletes the ref path itself: if msb's index
-     * ever loses track of an artifact without deleting it, the directory would
-     * otherwise linger under the cache dir forever. That recursive delete is
-     * gated on `looksLikeCheckpointArtifactDir` first — a `ref` is caller-
-     * supplied (a corrupt registry entry, a hand-edited env var, …), and a
-     * `fs.rm(ref, { recursive: true })` on an unverified path would happily
-     * wipe out an arbitrary directory that merely happens to share its name.
+     * Best-effort `msb snapshot rm <ref> -f` — "not found" is success, the
+     * same contract as `removeByName`. `ref` is passed FULL, never reduced to
+     * `path.basename(ref)`: EMPIRICALLY VERIFIED against a real msb 0.7.1
+     * binary, name-based removal does not resolve at all — the artifact PATH
+     * is the only address that reliably works (see `MsbCommands.snapshotRemove`'s
+     * own doc). Every real caller already hands this the EFFECTIVE ref
+     * `createCheckpoint` returned (an absolute path since 0.7.1), so this is
+     * also simply correct for the common case, not just a defensive choice.
+     *
+     * One failure shape is deliberately NOT swallowed alongside "not found":
+     * msb refuses to remove a snapshot that is still the current HEAD of
+     * older siblings from the same source sandbox (see
+     * `isSnapshotHeadRemovalRefused`) — that refusal propagates as a
+     * `BackendError` naming msb's own remedy, rather than silently doing
+     * nothing, since automatic head rotation is out of scope for this method
+     * (see the checkpoints guide's cleanup section for the documented
+     * limitation).
+     *
+     * msb's own removal deletes both its index entry and the dest-dir
+     * artifact for a path ref, but afterwards this also best-effort
+     * recursively deletes the ref path itself: if msb's index ever loses
+     * track of an artifact without deleting it, the directory would otherwise
+     * linger under the cache dir forever. That recursive delete is gated on
+     * `looksLikeCheckpointArtifactDir` first — a `ref` is caller-supplied (a
+     * corrupt registry entry, a hand-edited env var, …), and a `fs.rm(ref, {
+     * recursive: true })` on an unverified path would happily wipe out an
+     * arbitrary directory that merely happens to share its name.
      */
     async removeCheckpoint(ref) {
         const msbPath = await this.msbPath();
         const isPathRef = path.isAbsolute(ref);
-        const name = isPathRef ? path.basename(ref) : ref;
-        await invoke(msbPath, MsbCommands.snapshotRemove(name), CHECKPOINT_TIMEOUT_MS).catch(() => { });
+        const result = await invoke(msbPath, MsbCommands.snapshotRemove(ref), CHECKPOINT_TIMEOUT_MS).catch(() => undefined);
+        if (result !== undefined && result.exitCode !== 0 && isSnapshotHeadRemovalRefused(result.stderr)) {
+            throw new BackendError(`msb snapshot rm ${ref} -f was refused (exit ${result.exitCode}): ${result.stderr.trim()} — this ` +
+                `checkpoint is still the newest snapshot of other, older ones from the same source sandbox; ` +
+                `select another snapshot as head first ('msb snapshot head ...', see msb's own message above), ` +
+                `or remove the older siblings first.`);
+        }
         if (isPathRef && (await looksLikeCheckpointArtifactDir(ref))) {
             await fs.rm(ref, { recursive: true, force: true }).catch(() => { });
         }
@@ -726,10 +1833,10 @@ export class MsbCliBackend {
     /**
      * `msb snapshot save <ref> <destFile>` — writes the `.tar.zst` artifact
      * `Checkpoints.exportTo` bundles into its own archive container. Never
-     * `--with-image` (see the checkpoints guide's own note on why: its import
-     * fails an integrity check in 0.6.6, so archives never bundle the OCI
-     * image — the destination machine pulls it on the restored container's
-     * first boot).
+     * `--with-image` (see the checkpoints guide's own note: this library
+     * doesn't bundle the OCI image into the archive, so the destination
+     * machine pulls it on the restored container's first boot — upstream
+     * supports bundling it, this library just doesn't use that yet).
      *
      * On Windows, msb 0.6.7 and 0.6.8 fail this call every single time: they
      * finish writing the archive to a staging file beside the destination and
@@ -757,51 +1864,66 @@ export class MsbCliBackend {
         }
     }
     /**
-     * `msb snapshot load <archive>`, then resolves the EFFECTIVE ref: msb
-     * writes the import under a digest-derived directory name it never lets
-     * the caller choose (never the archive's own recorded `ref`), parsed from
-     * the printed artifact path's basename (see `parseImportedDigestDirName`).
+     * `msb snapshot load <archive> --dest <checkpointsDir>`, then resolves the
+     * EFFECTIVE ref: EMPIRICALLY VERIFIED against a real msb 0.7.1 binary, a
+     * successful load prints a `group msb-<hex>: head snap_<digest>
+     * (Initialized)` line, a digest line, and finally the loaded artifact's
+     * own absolute path as its LAST line — `<checkpointsDir>/<generated-
+     * group>/snap_<digest>`, never the archive's own recorded `ref` — parsed
+     * back out by `parseImportedArtifactPath` (the same last-non-empty-line,
+     * must-be-absolute defensive pattern `parseSnapshotCreateArtifactPath`
+     * uses for `snapshot create`). `checkpointsDir` is always this backend's
+     * own checkpoints cache directory (`<cacheDir>/checkpoints`, the same
+     * directory `checkpointRef()` mints created-checkpoint refs under) —
+     * omitting `--dest` would import into msb's own global default snapshot
+     * store instead, outside anywhere this library looks for or cleans up
+     * checkpoints. Created fresh (mkdir -p) before the load, since nothing
+     * guarantees a caller ever created a checkpoint locally first (an
+     * imported-only machine has no reason to have this directory yet).
+     *
+     * This replaces the pre-0.7.1 shape entirely: `snapshot load` used to
+     * write under a digest-derived directory name with no `--dest` of its
+     * own, so this method had to parse out just that bare NAME and then
+     * separately CONFIRM it via `msb snapshot list --format json` before
+     * handing it back (the only way to get a usable ref at all, since the
+     * bare name alone still had to resolve against msb's default store). 0.7.1
+     * prints the full, directly-usable, already-`--dest`-scoped path as part
+     * of `load`'s own output, so that whole list-and-confirm round trip is
+     * gone — dead code that this migration deletes outright, not merely
+     * bypassed.
+     *
      * An already-exists failure — msb's own content-addressed dedup — is
      * treated as success, since the artifact is already present under that
-     * digest either way; any OTHER import failure surfaces msb's own stderr.
-     * The digest-dir basename is then CONFIRMED present via `msb snapshot
-     * list --format json` (matching it against each entry's
-     * `name`/`artifact_path`) and returned as-is — never the entry's `digest`
-     * field. Live-verified against msb 0.6.8: the full `sha256:<64hex>`
-     * digest does not resolve as a snapshot ref at all (`msb snapshot inspect
-     * sha256:<full>` fails "snapshot not found"); only the digest-dir name
-     * resolves for `inspect`/`rm`/`run --from-snapshot`, so it — not the full
-     * digest — is the ref this must hand back for `hasCheckpoint` and every
-     * other snapshot-ref call to keep working. `_ref` (the archive's own
-     * recorded ref) is unused here — msb's importer never takes one, unlike
-     * docker's, where the effective ref really is the ref passed in.
+     * digest either way, and its stderr is parsed the same way as a success's
+     * stdout; any OTHER import failure surfaces msb's own stderr in a
+     * `BackendError`, and unparseable output (no recognizable absolute last
+     * line — e.g. only the "group ... (Initialized)" line, msb's OWN wording
+     * for a state that is not itself a path) throws a `BackendError` quoting
+     * the raw output verbatim rather than misreading a status line as a ref.
+     * `_ref` (the archive's own recorded ref) is unused here — msb's importer
+     * never takes one, unlike docker's, where the effective ref really is the
+     * ref passed in.
      */
     async importCheckpoint(srcFile, _ref) {
         const msbPath = await this.msbPath();
-        const imported = await invoke(msbPath, MsbCommands.snapshotImport(srcFile), CHECKPOINT_TIMEOUT_MS);
-        let digestDirName;
+        const checkpointsDir = path.join(cacheDir(), "checkpoints");
+        await fs.mkdir(checkpointsDir, { recursive: true });
+        const imported = await invoke(msbPath, MsbCommands.snapshotImport(srcFile, checkpointsDir), CHECKPOINT_TIMEOUT_MS);
+        let artifactPath;
         if (imported.exitCode === 0) {
-            digestDirName = parseImportedDigestDirName(imported.stdout);
+            artifactPath = parseImportedArtifactPath(imported.stdout);
         }
         else if (isSnapshotAlreadyExistsError(imported.stderr)) {
-            digestDirName = parseImportedDigestDirName(imported.stderr);
+            artifactPath = parseImportedArtifactPath(imported.stderr);
         }
         else {
-            throw new BackendError(`msb snapshot load ${srcFile} failed (exit ${imported.exitCode}): ${imported.stderr.trim()}`);
+            throw new BackendError(`msb snapshot load ${srcFile} --dest ${checkpointsDir} failed (exit ${imported.exitCode}): ${imported.stderr.trim()}`);
         }
-        if (digestDirName === undefined) {
-            throw new BackendError(`msb snapshot load ${srcFile} did not print a recognizable artifact path — output:\n` +
-                `${imported.stdout}${imported.stderr}`);
+        if (artifactPath === undefined) {
+            throw new BackendError(`msb snapshot load ${srcFile} --dest ${checkpointsDir} did not print a recognizable artifact path as its ` +
+                `last line — output:\n${imported.stdout}${imported.stderr}`);
         }
-        const list = await invoke(msbPath, MsbCommands.snapshotList(), CHECKPOINT_TIMEOUT_MS);
-        if (list.exitCode !== 0) {
-            throw new BackendError(`msb snapshot list failed (exit ${list.exitCode}): ${list.stderr.trim()}`);
-        }
-        const confirmedRef = confirmDigestDirNamePresent(parseSnapshotList(list.stdout), digestDirName);
-        if (confirmedRef === undefined) {
-            throw new BackendError(`imported snapshot '${digestDirName}' from ${srcFile} did not appear in 'msb snapshot list' — could not confirm the import`);
-        }
-        return confirmedRef;
+        return artifactPath;
     }
     async runningSandboxNames(msbPath) {
         const result = await invoke(msbPath, MsbCommands.ls(), LOGS_TIMEOUT_MS);
@@ -845,10 +1967,10 @@ export class MsbCliBackend {
         return (await invoke(msbPath, MsbCommands.logs(handle.id), LOGS_TIMEOUT_MS)).stdout;
     }
     /**
-     * `msb logs -f` never exits once the sandbox stops (confirmed against the
-     * real msb binary — it blocks on read forever instead of the documented
-     * clean exit). A watchdog polls `msb ls` in the background; the instant
-     * the sandbox leaves Running it quiesces the stuck follow child FIRST
+     * `msb logs -f` never exits on its own once the sandbox stops (confirmed
+     * against the real msb 0.7.1 binary — it just never exits, instead of the
+     * documented clean exit). A watchdog polls `msb ls` in the background; the
+     * instant the sandbox leaves Running it quiesces the stuck follow child FIRST
      * (kill it, wait for the reader to finish draining whatever was already
      * buffered) so `delivered` reflects everything the live stream will ever
      * produce, THEN does one authoritative non-follow `msb logs` fetch and
@@ -1057,11 +2179,17 @@ export class MsbCliBackend {
         // Nothing was created for ensureNetwork(); nothing to remove.
     }
     /**
-     * Networks are emulated because there is no bridge/subnet the current
-     * msb exposes on macOS — the only data path into a running sandbox is the
-     * exec channel. Four concerns, each its own guard: reject duplicate guest
-     * ports, validate every alias (they get shell-interpolated), probe for
-     * `nc`, then install `/etc/hosts` aliases and spawn one tunnel per link.
+     * Networks are emulated because msb gives sandboxes no network shared with
+     * each other, and TCP and UDP links take DIFFERENT routes: a TCP link is
+     * relayed over the exec channel, a UDP link's in-guest forwarder sends
+     * through the sandbox's host gateway to the target's published port.
+     * Validate first (duplicate guest ports, alias charset — both get
+     * shell-interpolated below), then probe for `nc` (every link needs it)
+     * and, only when a UDP link is present, for the forwarder's stricter
+     * dependencies (`-u`/`-e`, `timeout`). `/etc/hosts` aliases install once,
+     * shared by both protocols. From there each link takes its own path: a
+     * TCP link gets an `ExecTunnel`, unchanged; a UDP link gets
+     * `installUdpLink`'s forwarder script.
      */
     async installNetworkLinks(handle, links) {
         if (links.length === 0) {
@@ -1074,18 +2202,60 @@ export class MsbCliBackend {
         if (ncProbe.exitCode !== 0) {
             throw new UnsupportedByBackendError(`network links (no nc/busybox in consumer image '${handle.spec.image}')`, this.name, "run this test with RIGHTSIZE_BACKEND=docker instead");
         }
+        const udpLinks = links.filter((link) => link.protocol === "udp");
+        if (udpLinks.length > 0) {
+            const udpProbe = await this.exec(handle, ["sh", "-c", udpForwarderProbeScript()]);
+            if (udpProbe.exitCode !== 0) {
+                throw new UnsupportedByBackendError(`UDP network links (consumer image '${handle.spec.image}' has no busybox-style nc with -u/-e, or no timeout)`, this.name, "run with the docker backend");
+            }
+        }
         const hostsResult = await this.exec(handle, ["sh", "-c", hostsAliasScript(links)]);
         if (hostsResult.exitCode !== 0) {
             throw new BackendError(`failed to install /etc/hosts aliases in ${handle.id}: ${hostsResult.stderr}`);
         }
         const state = this.handles.get(handle.id);
         for (const link of links) {
+            if (link.protocol === "udp") {
+                await this.installUdpLink(handle, link);
+                continue;
+            }
             const tunnel = new ExecTunnel(msbPath, handle.id, link);
             if (state !== undefined) {
                 state.resources.push(tunnel);
             }
         }
     }
+    /**
+     * One UDP link: installs and detached-launches its forwarder script, then
+     * polls `/proc/net/udp{,6}` until the guest port is actually bound — the
+     * launch exec succeeding only proves the script started, not that its
+     * listener has bound yet, and `nc -u -l` itself prints nothing to signal
+     * that. No teardown counterpart, unlike `ExecTunnel`: the forwarder is a
+     * plain guest process with no host-side resource of its own, and guest
+     * processes die with the sandbox. A checkpoint reboot's link replay (see
+     * `GenericContainer.checkpoint`) reruns this exactly like a fresh install
+     * — `/tmp` is tmpfs, so the rebooted guest has no forwarder script left
+     * to find, only a fresh one this rewrites.
+     */
+    async installUdpLink(handle, link) {
+        const install = await this.exec(handle, ["sh", "-c", installUdpForwarderScript(link.guestPort, link.targetHostPort)]);
+        if (install.exitCode !== 0) {
+            throw new BackendError(`failed to install the UDP forwarder for guest port ${link.guestPort} in ${handle.id}: ${install.stderr}`);
+        }
+        const deadline = Date.now() + this.udpLinkReadinessTimeoutMs;
+        for (;;) {
+            const probe = await this.exec(handle, ["sh", "-c", udpReadinessProbeScript(link.guestPort)]);
+            if (probe.exitCode === 0) {
+                return;
+            }
+            if (Date.now() >= deadline) {
+                const log = await this.exec(handle, ["sh", "-c", `tail -c 2000 ${udpForwarderLogPath(link.guestPort)} 2>/dev/null`]);
+                throw new BackendError(`UDP forwarder for guest port ${link.guestPort} in ${handle.id} never bound within ` +
+                    `${this.udpLinkReadinessTimeoutMs / 1000}s; forwarder log tail:\n${log.stdout}`);
+            }
+            await sleep(this.udpLinkReadinessPollMs);
+        }
+    }
     /**
      * `msb copy -q <hostPath> <name>:<containerPath>` — the transfer only;
      * `GenericContainer.copyFileToContainer()` already confirmed the sandbox