rightsize 0.7.13 → 0.7.15

package/README.md

@@ -213,7 +213,9 @@ backend-specific rather than behavioral divergences:
   make it durable and rediscoverable across runs via `Checkpoints.find`/
   `list`/`remove`, registered under the rightsize cache dir. `Checkpoints.exportTo`/
   `importFrom` bundle a checkpoint into a portable archive for moving it
-  between machines and CI caches. See
+  between machines and CI caches. Files added with `withCopyFileToContainer`
+  are mounts of host files and are not part of a checkpoint: add them again
+  on the `fromCheckpoint()` container. See
   [Checkpoint / restore](https://ngriaznov.github.io/rightsize-node/guide/checkpoints).
 - **Runtime file copy.** `copyFileToContainer` / `copyContentToContainer` /
   `copyFileFromContainer` move files and directories into or out of an

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

@@ -0,0 +1,47 @@
+/**
+ * True if `output` (an `msb run` or `msb restore` invocation's combined
+ * stdout+stderr) is msb giving up on a boot because the sandbox process had
+ * already exited cleanly, without leaving a boot-error record, by the time the
+ * host went to connect to the guest agent. Captured on a Windows CI runner
+ * (a brokered restore, where PowerShell decorated the output and mangled the
+ * arrow):
+ *
+ * ```text
+ * msb.exe : error: failed to start "rz-731fdcdc-8"
+ * At line:1 char:1
+ * ...
+ *   → other: sandbox process exited (exit code: 0) before agent relay became available
+ *   → run `msb logs --source system rz-731fdcdc-8` for full diagnostics
+ * ```
+ *
+ * and, undecorated, from an attached `msb run`:
+ *
+ * ```text
+ * error: failed to start "rz-731fdcdc-8"
+ *   → other: sandbox process exited (exit code: 0) before agent relay became available
+ *   → run `msb logs --source system rz-731fdcdc-8` for full diagnostics
+ * ```
+ *
+ * The status in parentheses is Rust's `ExitStatus` Display: `exit code: N` on
+ * Windows (hex for high-bit codes, `exit code: 0xc0000409`), `exit status: N`
+ * or `signal: N (SIGABRT)` on Unix. Only a clean exit is the transient: it has
+ * been seen only under load, on attached run boots and on restores, and the
+ * same boot succeeds a moment later. A crash exit with the same message is
+ * deterministic (a TAB in a baked env var made msb 0.6.x abort with `signal: 6
+ * (SIGABRT)` every time, see the Cassandra module) and fails identically on a
+ * retry, so it is left as an ordinary boot failure.
+ *
+ * Matches two independent substrings, not the whole sentence: the arrow, the
+ * `other:` and `error:` prefixes and the line structure all change with the
+ * host's console and with PowerShell's capture, and no platform gate is
+ * needed. The closing parenthesis in the exit marker keeps `(exit code:
+ * 0xc0000409)` and `(exit code: 10)` from matching.
+ *
+ * What msb leaves behind is the stopped sandbox record under the name, which
+ * makes a plain same-name retry unsafe (`msb run` would restart the persisted
+ * config and ignore its new flags, `msb restore` refuses with "already
+ * exists"), so the caller removes it with `msb rm -f` first and boots again
+ * under the same name, exactly once.
+ */
+export declare function isAgentRelayUnavailable(output: string): boolean;
+//# sourceMappingURL=agent-relay.d.ts.map

package/dist/backend-msb/agent-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-relay.d.ts","sourceRoot":"","sources":["../../src/backend-msb/agent-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK/D"}

package/dist/backend-msb/agent-relay.js

@@ -0,0 +1,50 @@
+/**
+ * True if `output` (an `msb run` or `msb restore` invocation's combined
+ * stdout+stderr) is msb giving up on a boot because the sandbox process had
+ * already exited cleanly, without leaving a boot-error record, by the time the
+ * host went to connect to the guest agent. Captured on a Windows CI runner
+ * (a brokered restore, where PowerShell decorated the output and mangled the
+ * arrow):
+ *
+ * ```text
+ * msb.exe : error: failed to start "rz-731fdcdc-8"
+ * At line:1 char:1
+ * ...
+ *   → other: sandbox process exited (exit code: 0) before agent relay became available
+ *   → run `msb logs --source system rz-731fdcdc-8` for full diagnostics
+ * ```
+ *
+ * and, undecorated, from an attached `msb run`:
+ *
+ * ```text
+ * error: failed to start "rz-731fdcdc-8"
+ *   → other: sandbox process exited (exit code: 0) before agent relay became available
+ *   → run `msb logs --source system rz-731fdcdc-8` for full diagnostics
+ * ```
+ *
+ * The status in parentheses is Rust's `ExitStatus` Display: `exit code: N` on
+ * Windows (hex for high-bit codes, `exit code: 0xc0000409`), `exit status: N`
+ * or `signal: N (SIGABRT)` on Unix. Only a clean exit is the transient: it has
+ * been seen only under load, on attached run boots and on restores, and the
+ * same boot succeeds a moment later. A crash exit with the same message is
+ * deterministic (a TAB in a baked env var made msb 0.6.x abort with `signal: 6
+ * (SIGABRT)` every time, see the Cassandra module) and fails identically on a
+ * retry, so it is left as an ordinary boot failure.
+ *
+ * Matches two independent substrings, not the whole sentence: the arrow, the
+ * `other:` and `error:` prefixes and the line structure all change with the
+ * host's console and with PowerShell's capture, and no platform gate is
+ * needed. The closing parenthesis in the exit marker keeps `(exit code:
+ * 0xc0000409)` and `(exit code: 10)` from matching.
+ *
+ * What msb leaves behind is the stopped sandbox record under the name, which
+ * makes a plain same-name retry unsafe (`msb run` would restart the persisted
+ * config and ignore its new flags, `msb restore` refuses with "already
+ * exists"), so the caller removes it with `msb rm -f` first and boots again
+ * under the same name, exactly once.
+ */
+export function isAgentRelayUnavailable(output) {
+    return (output.includes("before agent relay became available") &&
+        (output.includes("(exit code: 0)") || output.includes("(exit status: 0)")));
+}
+//# sourceMappingURL=agent-relay.js.map

package/dist/backend-msb/agent-relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-relay.js","sourceRoot":"","sources":["../../src/backend-msb/agent-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,CACL,MAAM,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QACtD,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAC3E,CAAC;AACJ,CAAC"}

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

@@ -79,6 +79,7 @@ export declare class MsbCliBackend implements SandboxBackend {
     private platformOverrideForTests;
     private udpLinkReadinessPollMs;
     private udpLinkReadinessTimeoutMs;
+    private agentRelayRetryDelayMs;
     constructor(msbPathPromise: Promise<string>, options?: MsbCliBackendOptions);
     /**
      * Whether this process should treat itself as running on Windows for
@@ -126,17 +127,18 @@ export declare class MsbCliBackend implements SandboxBackend {
     /**
      * A boot attempt wrapped in every classified-transient retry this backend
      * 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 (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.
+     * one-shot image-cache heal. (The one-shot agent-relay retry sits one level
+     * lower, inside `bootOnce`, so each `bootOnce` call below gets it too.)
+     * Both the ordinary `start()` path and the checkpoint cycle's post-snapshot
+     * reboot come through here — a reboot 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
@@ -166,6 +168,27 @@ export declare class MsbCliBackend implements SandboxBackend {
      * doc.
      */
     private bootClassified;
+    /**
+     * One boot, with its one agent-relay retry. Every caller that boots a
+     * sandbox goes through here: `bootClassified`'s first attempt and each of
+     * its own retries (install-lock poll, state-database, image-cache heal), and
+     * through it the ordinary `start()` path, the reuse boot, direct and
+     * brokered restores, and the checkpoint reboot's fresh-name loops
+     * (`retryRestoreAfterAccessDenied`, `rebootUnderFreshName`).
+     *
+     * When an attempt's sandbox process exits cleanly before msb's agent relay
+     * comes up (see `isAgentRelayUnavailable`) this removes the failed sandbox
+     * (`msb rm -f <name>`, result ignored — msb leaves the record behind as
+     * Stopped, and a plain same-name `run` would restart that persisted config
+     * while a same-name `restore` is refused as "already exists"), waits
+     * `AGENT_RELAY_RETRY_DELAY_MS`, and boots again with the SAME name, spec and
+     * `restoreLaunchMode`. Exactly once: a second relay failure throws a
+     * `BackendError` carrying that attempt's output, and any other error from
+     * either attempt propagates untouched for the caller's own policy. The name
+     * never changes, so the reaper ledger, `handles` and `startedNames` need no
+     * adjustment — a failed attempt registers nothing in the last two.
+     */
+    private bootOnce;
     /**
      * One boot attempt, dispatched by shape: an ordinary spec (no
      * `checkpointRef`) drives `run()`'s ATTACHED supervision model
@@ -177,7 +200,7 @@ export declare class MsbCliBackend implements SandboxBackend {
      * (irrelevant to `bootRunOnce`'s own ordinary `run` path, which never
      * brokers — see `RestoreLaunchMode`'s own doc).
      */
-    private bootOnce;
+    private bootAttempt;
     /**
      * One RUN boot attempt: spawns ATTACHED `msb run`, which stays alive as
      * the sandbox's own supervisor for its whole lifetime, and polls
@@ -193,7 +216,9 @@ export declare class MsbCliBackend implements SandboxBackend {
      * 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 —
+     * throws `PortBindConflictError`, a sandbox process that exited before its
+     * agent relay came up throws `AgentRelayUnavailableError` (retried once by
+     * `bootOnce`), 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);
@@ -221,9 +246,9 @@ export declare class MsbCliBackend implements SandboxBackend {
      *      "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
+     *      port-bind-conflict, agent-relay — 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
@@ -277,12 +302,16 @@ export declare class MsbCliBackend implements SandboxBackend {
      * (`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.
+     * stderr and exit code got back to this process differs. One of those
+     * signatures is not transient: msb 0.7.8 refusing a restore that leaves out
+     * a file copied in at start (`isRestoreMissingBindingsFailure`) is checked
+     * first and thrown as `CheckpointMissingCopiedFilesError`, which no caller
+     * retries. 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;
     /**
@@ -608,8 +637,9 @@ export declare class MsbCliBackend implements SandboxBackend {
      * 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.
+     * `env`, `mounts`, and `memoryLimitMb` are untouched by the rename — same
+     * ports, env, copied files 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
@@ -676,6 +706,19 @@ 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.
      *
+     * Files copied in at start (`handle.spec.mounts`) are bind mounts of host
+     * files, so the snapshot holds no content for them. The reboot mounts each
+     * one again from its host file (`MsbCommands.restore` emits one `--volume`
+     * per mount), which is also what msb 0.7.8 requires: it refuses a restore
+     * that leaves one out. The host files therefore have to still exist, and
+     * this method checks that, before any of the above, with
+     * `CheckpointHostFileMissingError` (ahead of the stop, so a missing file
+     * never costs the caller its running sandbox). A reuse sandbox adopted
+     * through `findRunning` carries the builder's own spec, mounts included
+     * (they are part of the reuse identity), so its reboot supplies them like
+     * any other. One adopted by a process whose backend never called `create()`
+     * for it has no handle state and is refused before anything is stopped.
+     *
      * `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

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

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

package/dist/backend-msb/backend.js

@@ -2,7 +2,8 @@ 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, CheckpointWorkloadCommandMissingError, } from "../core/errors.js";
+import { BackendError, PortBindConflictError, UnsupportedByBackendError, TmpfsRootCheckpointError, CheckpointWorkloadCommandMissingError, CheckpointMissingCopiedFilesError, } from "../core/errors.js";
+import { requireCopiedHostFilesExist } from "../core/checkpoint/copied-files.js";
 import { cacheDir } from "../core/cache-dir.js";
 import { nextSandboxName } from "../core/sandbox-name.js";
 import { trackSandbox, untrackSandbox } from "../core/reaper/init.js";
@@ -13,6 +14,7 @@ import { invoke, CLOSED_STDIN } from "./invoke.js";
 import { isPortBindConflictOutput } from "./port-conflict.js";
 import { isImageCacheCorruption } from "./image-cache.js";
 import { isMsbStateDbError } from "./state-db.js";
+import { isAgentRelayUnavailable } from "./agent-relay.js";
 import { isAgentEndpointNotReady } from "./agent-endpoint.js";
 import { isSnapshotNotFoundError } from "./snapshot-not-found.js";
 import { isSnapshotAlreadyExistsError, parseImportedArtifactPath } from "./snapshot-import.js";
@@ -24,6 +26,7 @@ import { requireNoDuplicateGuestPorts, requireAliasesAreValid, hostsAliasScript,
 import { ExecTunnel } from "./exec-tunnel.js";
 import { isRestoreAccessDeniedFailure } from "./restore-access-denied.js";
 import { isSandboxAlreadyExistsFailure } from "./sandbox-already-exists.js";
+import { isRestoreMissingBindingsFailure } from "./restore-missing-bindings.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;
@@ -131,6 +134,20 @@ class StateDbError extends Error {
         this.output = output;
     }
 }
+/**
+ * The boot failure `bootOnce` retries once — the sandbox process exited
+ * cleanly before msb's agent relay came up (see `isAgentRelayUnavailable`).
+ * Thrown from both `bootRunOnce` and `bootRestoreOnce`, and caught by
+ * `bootOnce` itself, so unlike its siblings above it never reaches
+ * `bootClassified` or any caller of it.
+ */
+class AgentRelayUnavailableError extends Error {
+    output;
+    constructor(output) {
+        super(`msb sandbox process exited before its agent relay came up:\n${output}`);
+        this.output = output;
+    }
+}
 /**
  * True if `output` (an `msb run` invocation's combined output) is msb
  * refusing to run anything while its internal install lock is held. Captured
@@ -211,6 +228,14 @@ class SandboxAlreadyExistsError extends Error {
  * to commit; the retry's own `msb run` startup dwarfs this either way.
  */
 const STATE_DB_RETRY_DELAY_MS = 500;
+/**
+ * How long to wait between a boot whose sandbox process exited before its
+ * agent relay came up (see `isAgentRelayUnavailable`) and its one retry. The
+ * failed sandbox is removed (`msb rm -f`) first; the pause just lets msb and
+ * the OS finish tearing the dead process down before the same name boots
+ * again.
+ */
+const AGENT_RELAY_RETRY_DELAY_MS = 2_000;
 /**
  * How long the boot path keeps polling while msb's install-operation lock is
  * held, and the pause between attempts (see `isMsbInstallLockActive`) —
@@ -489,6 +514,11 @@ export class MsbCliBackend {
     // red-proof runs in milliseconds rather than the real 5s.
     udpLinkReadinessPollMs = UDP_LINK_READINESS_POLL_MS;
     udpLinkReadinessTimeoutMs = UDP_LINK_READINESS_TIMEOUT_MS;
+    // Test-only override seam for bootOnce's pause before its one agent-relay
+    // retry — defaults to the real AGENT_RELAY_RETRY_DELAY_MS constant, reached
+    // the same unsafe-cast way as the seams above so a retry test does not
+    // block for the real 2s.
+    agentRelayRetryDelayMs = AGENT_RELAY_RETRY_DELAY_MS;
     constructor(msbPathPromise, options = {}) {
         this.msbPathPromise = msbPathPromise;
         this.restoreBroker = options.restoreBroker ?? realRestoreBroker;
@@ -560,17 +590,18 @@ export class MsbCliBackend {
     /**
      * A boot attempt wrapped in every classified-transient retry this backend
      * 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 (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.
+     * one-shot image-cache heal. (The one-shot agent-relay retry sits one level
+     * lower, inside `bootOnce`, so each `bootOnce` call below gets it too.)
+     * Both the ordinary `start()` path and the checkpoint cycle's post-snapshot
+     * reboot come through here — a reboot 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
@@ -686,6 +717,50 @@ export class MsbCliBackend {
                 `directory under MSB_HOME).\nfirst attempt:\n${firstOutput}\nafter heal + retry:\n${second.output}`);
         }
     }
+    /**
+     * One boot, with its one agent-relay retry. Every caller that boots a
+     * sandbox goes through here: `bootClassified`'s first attempt and each of
+     * its own retries (install-lock poll, state-database, image-cache heal), and
+     * through it the ordinary `start()` path, the reuse boot, direct and
+     * brokered restores, and the checkpoint reboot's fresh-name loops
+     * (`retryRestoreAfterAccessDenied`, `rebootUnderFreshName`).
+     *
+     * When an attempt's sandbox process exits cleanly before msb's agent relay
+     * comes up (see `isAgentRelayUnavailable`) this removes the failed sandbox
+     * (`msb rm -f <name>`, result ignored — msb leaves the record behind as
+     * Stopped, and a plain same-name `run` would restart that persisted config
+     * while a same-name `restore` is refused as "already exists"), waits
+     * `AGENT_RELAY_RETRY_DELAY_MS`, and boots again with the SAME name, spec and
+     * `restoreLaunchMode`. Exactly once: a second relay failure throws a
+     * `BackendError` carrying that attempt's output, and any other error from
+     * either attempt propagates untouched for the caller's own policy. The name
+     * never changes, so the reaper ledger, `handles` and `startedNames` need no
+     * adjustment — a failed attempt registers nothing in the last two.
+     */
+    async bootOnce(msbPath, handle, state, restoreLaunchMode = "direct") {
+        try {
+            await this.bootAttempt(msbPath, handle, state, restoreLaunchMode);
+            return;
+        }
+        catch (first) {
+            if (!(first instanceof AgentRelayUnavailableError)) {
+                throw first;
+            }
+        }
+        await invoke(msbPath, MsbCommands.rmForce(handle.id), STOP_TIMEOUT_MS).catch(() => { });
+        await sleep(this.agentRelayRetryDelayMs);
+        try {
+            await this.bootAttempt(msbPath, handle, state, restoreLaunchMode);
+        }
+        catch (second) {
+            if (!(second instanceof AgentRelayUnavailableError)) {
+                throw second;
+            }
+            throw new BackendError(`msb ${handle.spec.checkpointRef !== undefined ? "restore" : "run"} for sandbox ${handle.id}: msb's ` +
+                `sandbox process exited before its agent relay came up on both attempts (the retry ran after ` +
+                `'msb rm -f' of the failed sandbox and a short pause).\nlast attempt:\n${second.output}`);
+        }
+    }
     /**
      * One boot attempt, dispatched by shape: an ordinary spec (no
      * `checkpointRef`) drives `run()`'s ATTACHED supervision model
@@ -697,7 +772,7 @@ export class MsbCliBackend {
      * (irrelevant to `bootRunOnce`'s own ordinary `run` path, which never
      * brokers — see `RestoreLaunchMode`'s own doc).
      */
-    async bootOnce(msbPath, handle, state, restoreLaunchMode = "direct") {
+    async bootAttempt(msbPath, handle, state, restoreLaunchMode) {
         state.logTail = [];
         state.attachedExited = false;
         if (handle.spec.checkpointRef !== undefined) {
@@ -721,7 +796,9 @@ export class MsbCliBackend {
      * 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 —
+     * throws `PortBindConflictError`, a sandbox process that exited before its
+     * agent relay came up throws `AgentRelayUnavailableError` (retried once by
+     * `bootOnce`), 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);
@@ -761,6 +838,9 @@ export class MsbCliBackend {
                 if (isPortBindConflictOutput(output)) {
                     throw new PortBindConflictError(`msb run for sandbox ${handle.id} could not bind a host port: ${output}`);
                 }
+                if (isAgentRelayUnavailable(output)) {
+                    throw new AgentRelayUnavailableError(output);
+                }
                 if (exited.code === 0 && (await this.isCompletedFastExit(msbPath, handle.id))) {
                     // The workload ran to completion before this poll loop ever
                     // observed Running — see isCompletedFastExit's own doc. Started-
@@ -818,9 +898,9 @@ export class MsbCliBackend {
      *      "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
+     *      port-bind-conflict, agent-relay — 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
@@ -874,12 +954,16 @@ export class MsbCliBackend {
      * (`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.
+     * stderr and exit code got back to this process differs. One of those
+     * signatures is not transient: msb 0.7.8 refusing a restore that leaves out
+     * a file copied in at start (`isRestoreMissingBindingsFailure`) is checked
+     * first and thrown as `CheckpointMissingCopiedFilesError`, which no caller
+     * retries. 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"
@@ -887,6 +971,15 @@ export class MsbCliBackend {
             : await this.launchRestoreDirect(msbPath, handle, state);
         if (launch.kind === "completed") {
             const { exitCode, output } = launch;
+            // First, so none of the transient classifiers below can claim it, and
+            // thrown as the public error itself rather than an internal one: nothing
+            // retries it (`bootClassified`, `bootOnce` and both fresh-name loops
+            // rethrow what they do not recognise), because the same restore is
+            // refused the same way every time. Direct and brokered attempts both
+            // pass through here, so this is the one place that classifies it.
+            if (isRestoreMissingBindingsFailure(output)) {
+                throw new CheckpointMissingCopiedFilesError(handle.id, handle.spec.checkpointRef ?? "(unknown)", output);
+            }
             if (isImageCacheCorruption(output)) {
                 throw new ImageCacheCorruptionError(output);
             }
@@ -905,6 +998,9 @@ export class MsbCliBackend {
             if (isSandboxAlreadyExistsFailure(output)) {
                 throw new SandboxAlreadyExistsError(output);
             }
+            if (isAgentRelayUnavailable(output)) {
+                throw new AgentRelayUnavailableError(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}`);
@@ -1557,8 +1653,9 @@ export class MsbCliBackend {
      * 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.
+     * `env`, `mounts`, and `memoryLimitMb` are untouched by the rename — same
+     * ports, env, copied files 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
@@ -1625,6 +1722,19 @@ 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.
      *
+     * Files copied in at start (`handle.spec.mounts`) are bind mounts of host
+     * files, so the snapshot holds no content for them. The reboot mounts each
+     * one again from its host file (`MsbCommands.restore` emits one `--volume`
+     * per mount), which is also what msb 0.7.8 requires: it refuses a restore
+     * that leaves one out. The host files therefore have to still exist, and
+     * this method checks that, before any of the above, with
+     * `CheckpointHostFileMissingError` (ahead of the stop, so a missing file
+     * never costs the caller its running sandbox). A reuse sandbox adopted
+     * through `findRunning` carries the builder's own spec, mounts included
+     * (they are part of the reuse identity), so its reboot supplies them like
+     * any other. One adopted by a process whose backend never called `create()`
+     * for it has no handle state and is refused before anything is stopped.
+     *
      * `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
@@ -1648,6 +1758,14 @@ export class MsbCliBackend {
             // away a running sandbox for.
             throw new TmpfsRootCheckpointError();
         }
+        // Same reasoning for the copied files: the reboot below mounts each one
+        // again from its host file (`msb restore --volume`, see
+        // `MsbCommands.restore`), so a host file that has gone missing would only
+        // be noticed after the source sandbox is stopped, snapshotted and
+        // removed. `GenericContainer.checkpoint()` runs the same check ahead of
+        // replacing a named checkpoint; this one covers a caller that reaches the
+        // backend directly.
+        await requireCopiedHostFilesExist(handle.spec.mounts);
         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
@@ -1731,7 +1849,7 @@ export class MsbCliBackend {
             const detail = err instanceof Error ? err.message : String(err);
             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 '${effectiveRef}', restorable via GenericContainer.fromCheckpoint().`);
+                `checkpoint '${effectiveRef}', restorable via GenericContainer.fromCheckpoint().`, err);
         }
         const freshName = rebootHandle.id;
         // The reboot succeeded under `freshName` — the WINNING attempt's own