rightsize 0.7.8 → 0.7.10

package/dist/backend-msb/backend.d.ts

@@ -1,5 +1,6 @@
 import type { SandboxBackend, SandboxHandle, FollowHandle, NetworkLink, ReaperKillCommand, BackendCapabilities } from "../core/backend.js";
 import type { ContainerSpec, ExecResult } from "../core/model.js";
+import { type RestoreBrokerLauncher } from "./restore-broker.js";
 /**
  * True if `output` (an `msb run` invocation's combined output) is msb
  * refusing to run anything while its internal install lock is held. Captured
@@ -23,6 +24,25 @@ import type { ContainerSpec, ExecResult } from "../core/model.js";
  * timestamp varies per occurrence.
  */
 export declare function isMsbInstallLockActive(output: string): boolean;
+/**
+ * Constructor options for {@link MsbCliBackend}. Every field is optional so
+ * every existing `new MsbCliBackend(msbPathPromise)` call site keeps
+ * compiling and behaving unchanged.
+ */
+export interface MsbCliBackendOptions {
+    /**
+     * The launcher POLICY v2's broker escalation calls through for every
+     * brokered restore attempt (see `RestoreLaunchMode`/`restore-broker.ts`).
+     * Defaults to `realRestoreBroker`, the real `powershell.exe`/WMI
+     * implementation — production code never needs to pass this. Tests inject
+     * a fake here instead of driving a real `powershell.exe`, the same role
+     * `checkpointRebootAlreadyExistsRetryBudgetMs` already plays for the
+     * retry budget itself, just as a constructor option rather than an
+     * unsafe-cast field, since production code (not only tests) needs a way to
+     * supply it.
+     */
+    restoreBroker?: RestoreBrokerLauncher;
+}
 /**
  * The attached-mode CLI driver: every sandbox this backend starts runs as a
  * held child process (`msb run`, no `-d`) because detached mode never
@@ -50,7 +70,22 @@ export declare class MsbCliBackend implements SandboxBackend {
     private readonly handles;
     private readonly startedNames;
     private resolvedMsbPath;
-    constructor(msbPathPromise: Promise<string>);
+    private checkpointRebootAlreadyExistsRetryBudgetMs;
+    private checkpointRebootAlreadyExistsRetryDelayMs;
+    private readonly restoreBroker;
+    private platformOverrideForTests;
+    constructor(msbPathPromise: Promise<string>, options?: MsbCliBackendOptions);
+    /**
+     * 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.
+     */
+    private isWindowsPlatform;
     private msbPath;
     create(spec: ContainerSpec): Promise<SandboxHandle>;
     /**
@@ -88,34 +123,288 @@ export declare class MsbCliBackend implements SandboxBackend {
      * 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.
      */
     private bootClassified;
     /**
-     * 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).
+     */
+    private bootOnce;
+    /**
+     * 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.
      */
-    private bootOnce;
+    private bootRunOnce;
+    /**
+     * 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.
+     */
+    private bootRestoreOnce;
+    /**
+     * `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.
+     */
+    private launchRestoreDirect;
+    /**
+     * `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.
+     */
+    private launchRestoreViaBroker;
+    /**
+     * 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.
+     */
+    private restoreBootFailureMessage;
+    /**
+     * 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.
+     */
+    private reviveWorkload;
+    /**
+     * 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).
+     */
+    private captureGuestWorkloadCmdline;
+    /**
+     * 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: SandboxHandle): ReadonlyArray<string> | undefined;
     /**
      * 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
@@ -139,30 +428,237 @@ export declare class MsbCliBackend implements SandboxBackend {
     private isCompletedFastExit;
     stop(handle: SandboxHandle): Promise<void>;
     remove(handle: SandboxHandle): Promise<void>;
+    /**
+     * `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.
+     */
+    private retryRestoreAfterAccessDenied;
+    /**
+     * `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.
+     */
+    private rebootUnderFreshName;
     /**
      * 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
@@ -174,19 +670,52 @@ export declare class MsbCliBackend implements SandboxBackend {
      *
      * 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.
      */
-    createCheckpoint(handle: SandboxHandle, ref: string): Promise<void>;
+    createCheckpoint(handle: SandboxHandle, ref: string): Promise<string>;
     /**
-     * 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.
      */
     removeCheckpoint(ref: string): Promise<void>;
     /**
@@ -233,24 +762,45 @@ export declare class MsbCliBackend implements SandboxBackend {
      */
     exportCheckpoint(ref: string, destFile: string): Promise<void>;
     /**
-     * `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.
      */
     importCheckpoint(srcFile: string, _ref: string): Promise<string>;
     private runningSandboxNames;