@opengeni/runtime 0.13.0 → 0.13.4

package/src/sandbox/exec-banner.ts

@@ -65,3 +65,18 @@ export function parseExecBannerExitCode(raw: string): number | null {
   const banner = parseExecResponseBanner(raw);
   return banner.kind === "exited" ? banner.exitCode : null;
 }
+
+// Detect the Modal "the exec-session you're writing to no longer exists" fact.
+// This is process-lifetime authority, so classify only the complete known
+// banner (or its bare provider form) carrying the exact tracked numeric id.
+export function isExecSessionLostBanner(out: string, execSessionId: number): boolean {
+  if (!out || !Number.isSafeInteger(execSessionId) || execSessionId < 0) return false;
+  const match = out.match(/^(?:write_stdin failed: )?session not found: (\d+)$/);
+  // JavaScript's `$` also matches immediately before one final line terminator.
+  // Requiring the regex match to consume the entire string keeps even that
+  // otherwise-special case fail-closed.
+  if (!match || match[0] !== out) return false;
+  // String equality is intentional: parseInt would normalize malformed facts
+  // such as `01` and can round an out-of-range integer into another identity.
+  return match[1] === String(execSessionId);
+}

package/src/sandbox/index.ts

@@ -32,7 +32,14 @@ import type {
 } from "@openai/agents/sandbox";
 import { PROVIDER_REGISTRY } from "./providers";
 import { SandboxConfigError, SandboxResumeStateUnavailableError } from "./errors";
-import { isSelfhostedProviderNotFoundError } from "./selfhosted/session";
+import { isProviderSandboxNotFoundError } from "./provider-errors";
+import {
+  readVerifiedWorkspaceArchive,
+  verifyRestoredWorkspace,
+  WorkspaceArchiveIntegrityError,
+  type VerifiedWorkspaceArchive,
+  type WorkspaceArchiveDescriptor,
+} from "./workspace-archive";
 import type { RuntimeMetricsHooks } from "../metrics";
 
 // Re-export the config-owned environment/port helpers from the leaf so the
@@ -62,6 +69,27 @@ export {
   type ProviderRegistration,
   type ProviderConstructionContext,
 } from "./providers";
+export {
+  classifyProviderSandboxFailure,
+  isProviderSandboxGoneDuringRoutedOperation,
+  isProviderSandboxNotFoundError,
+  isProviderSandboxTransientError,
+  type ProviderSandboxFailure,
+  type ProviderSandboxFailureKind,
+} from "./provider-errors";
+export {
+  WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+  WorkspaceArchiveIntegrityError,
+  captureVerifiedWorkspaceArchive,
+  fingerprintSandboxWorkspace,
+  parseWorkspaceArchiveDescriptor,
+  readVerifiedWorkspaceArchive,
+  verifyRestoredWorkspace,
+  type VerifiedWorkspaceArchive,
+  type WorkspaceArchiveDescriptor,
+  type WorkspaceArchiveIntegrityCode,
+  type WorkspaceTreeFingerprint,
+} from "./workspace-archive";
 export {
   ensureModalRegistryImage,
   modalSandboxAttributionEnvironment,
@@ -342,11 +370,18 @@ export {
 // currently-active backend (Modal or selfhosted) — flippable mid-turn, single
 // active at a time, fence-retrying on a swap race.
 export {
+  RoutingBackendRecoveryRequiredError,
+  RoutingMutationOutcomeUnknownError,
+  RoutingRetainedProcessNotFoundError,
   RoutingSandboxSession,
   RoutingUnsupportedError,
   type ActivePointer,
+  type DefaultBackendLossResult,
   type RoutableBackendSession,
   type ResolvedActiveBackend,
+  type RoutingRetainedProcess,
+  type RoutingRetainedProcessAdoption,
+  type RoutingRetainedProcessTerminalProof,
   type RoutingSandboxSessionDeps,
   type RoutingTransitionEvent,
 } from "./routing/routing-session";
@@ -592,24 +627,6 @@ export function readWorkspaceArchiveFromEnvelopeSessionState(
   }
 }
 
-function readWorkspaceArchivePairFromEnvelopeSessionState(sessionState: unknown): {
-  current?: Uint8Array;
-  previous?: Uint8Array;
-} {
-  if (!sessionState || typeof sessionState !== "object") {
-    return {};
-  }
-  const state = sessionState as { workspaceArchivePrev?: unknown };
-  const current = readWorkspaceArchiveFromEnvelopeSessionState(sessionState);
-  const previous = readWorkspaceArchiveFromEnvelopeSessionState({
-    workspaceArchive: state.workspaceArchivePrev,
-  });
-  return {
-    ...(current ? { current } : {}),
-    ...(previous ? { previous } : {}),
-  };
-}
-
 // The native snapshot-ref prefixes the @openai/agents-extensions modal client
 // encodes (snapshots.mjs `NATIVE_SNAPSHOT_PREFIXES`). The ref is
 // `<PREFIX>\n{"snapshot_id":"...",...}`. We re-implement the decode here because
@@ -764,8 +781,113 @@ export type EstablishedSandboxSession = {
   /** Set when a create-authorized reattach found the envelope's box GONE
    *  (provider NotFound) and fell through to cold-restore. */
   lostInstanceId?: string;
+  /** Exact durable archive revision verified byte-for-byte after hydration. */
+  restoredArchive?: WorkspaceArchiveDescriptor;
 };
 
+export class SandboxExecReadinessError extends Error {
+  readonly name = "SandboxExecReadinessError";
+
+  constructor(
+    public readonly backend: string,
+    public readonly code: "exec_probe_unavailable" | "exec_probe_timeout" | "exec_probe_failed",
+    public readonly timeoutMs: number,
+    public readonly exitCode: number | null = null,
+  ) {
+    super(
+      code === "exec_probe_timeout"
+        ? `sandbox creation timed out waiting for ${backend} command readiness after ${timeoutMs}ms`
+        : code === "exec_probe_unavailable"
+          ? `${backend} sandbox session does not expose an exec readiness probe`
+          : exitCode === null
+            ? `${backend} sandbox exec readiness probe did not return a command exit code`
+            : `${backend} sandbox exec readiness probe failed with exit code ${exitCode}`,
+    );
+  }
+}
+
+function sandboxExecProbeExitCode(result: unknown): number | null {
+  if (typeof result === "string") {
+    const match = result.match(/Process exited with code (-?\d+)/);
+    return match ? Number(match[1]) : null;
+  }
+  if (!result || typeof result !== "object") return null;
+  const candidate = result as {
+    exitCode?: unknown;
+    exit_code?: unknown;
+    code?: unknown;
+    status?: unknown;
+  };
+  for (const value of [candidate.exitCode, candidate.exit_code, candidate.code, candidate.status]) {
+    if (typeof value === "number") return value;
+  }
+  return null;
+}
+
+function sandboxExecProbeStillRunning(result: unknown): boolean {
+  if (typeof result === "string") return /Process running with session ID \d+/u.test(result);
+  if (!result || typeof result !== "object") return false;
+  const candidate = result as { sessionId?: unknown; session_id?: unknown };
+  return typeof candidate.sessionId === "number" || typeof candidate.session_id === "number";
+}
+
+/** A provider handle is not workspace readiness. Modal can return a handle
+ * before its command router accepts exec, so every create path must pass this
+ * bounded probe before atomically publishing the lease warm/ready. */
+export async function verifySandboxExecReadiness(
+  established: EstablishedSandboxSession,
+  timeoutMs = 15_000,
+): Promise<void> {
+  if (established.backendId !== "modal") return;
+  const session = established.session as {
+    exec?: (args: {
+      cmd: string;
+      yieldTimeMs?: number;
+      maxOutputTokens?: number;
+    }) => Promise<unknown>;
+    execCommand?: (args: {
+      cmd: string;
+      yieldTimeMs?: number;
+      maxOutputTokens?: number;
+    }) => Promise<unknown>;
+  };
+  const run = session.exec ?? session.execCommand;
+  if (!run) {
+    throw new SandboxExecReadinessError(established.backendId, "exec_probe_unavailable", timeoutMs);
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const result = await Promise.race([
+      run.call(session, {
+        cmd: "true",
+        yieldTimeMs: 1_000,
+        maxOutputTokens: 1_000,
+      }),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new SandboxExecReadinessError(established.backendId, "exec_probe_timeout", timeoutMs),
+            ),
+          timeoutMs,
+        );
+        if (timer && "unref" in timer && typeof timer.unref === "function") timer.unref();
+      }),
+    ]);
+    const exitCode = sandboxExecProbeExitCode(result);
+    if (sandboxExecProbeStillRunning(result) || exitCode !== 0) {
+      throw new SandboxExecReadinessError(
+        established.backendId,
+        "exec_probe_failed",
+        timeoutMs,
+        exitCode,
+      );
+    }
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 export type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
 
 // The structural slice we need from a provider SandboxClient to resume by id and
@@ -792,64 +914,6 @@ type ResumeCapableClient = {
  * an unrecognized error is treated as "not NotFound" (propagate), because a
  * false-positive recreate is the dangerous direction (double-spawn).
  */
-export function isProviderSandboxNotFoundError(backendId: string, error: unknown): boolean {
-  // selfhosted: agent-offline is NEVER a provider NotFound (the user's machine is
-  // not recreatable — a false NotFound would cold-create a RIVAL box). The
-  // selfhosted discriminator ALWAYS returns false; short-circuit so no goneMarker
-  // string match below can ever flip a selfhosted agent-offline error to true.
-  if (backendId === "selfhosted") {
-    return isSelfhostedProviderNotFoundError(error);
-  }
-  if (!error) {
-    return false;
-  }
-  const status =
-    (error as { status?: unknown; statusCode?: unknown }).status ??
-    (error as { statusCode?: unknown }).statusCode;
-  if (status === 404) {
-    return true;
-  }
-  const name =
-    typeof (error as { name?: unknown }).name === "string" ? (error as { name: string }).name : "";
-  const code =
-    typeof (error as { code?: unknown }).code === "string" ? (error as { code: string }).code : "";
-  const message =
-    error instanceof Error
-      ? error.message
-      : typeof error === "string"
-        ? error
-        : String((error as { message?: unknown })?.message ?? "");
-  const haystack = `${name} ${code} ${message}`.toLowerCase();
-  // Provider-agnostic "gone" markers (Modal: "sandbox … not found" / terminated;
-  // e2b/daytona/runloop: "not found" / "no longer running" / "terminated" /
-  // "does not exist"). Kept broad-but-conservative: it matches box-gone phrasing
-  // and never matches generic 5xx/transport errors.
-  const goneMarkers = [
-    "not found",
-    "no longer running",
-    "no longer exists",
-    "does not exist",
-    "doesn't exist",
-    "has been terminated",
-    "was terminated",
-    "is terminated",
-    "sandbox terminated",
-    "notfound",
-    "sandbox_not_found",
-    "box no longer running",
-  ];
-  // A "running"/"already exists" resume-conflict is explicitly NOT NotFound — the
-  // box is alive; recreating would double-spawn.
-  if (
-    haystack.includes("already running") ||
-    haystack.includes("still running") ||
-    haystack.includes("already exists")
-  ) {
-    return false;
-  }
-  return goneMarkers.some((marker) => haystack.includes(marker));
-}
-
 function readInstanceId(session: unknown): string {
   const state = (session as { state?: Record<string, unknown> }).state ?? {};
   const candidate =
@@ -910,6 +974,10 @@ export async function establishSandboxSessionFromEnvelope(
     backendOverride?: SandboxBackend;
     environment?: Record<string, string>;
     onSandboxCreated?: SandboxCreatedCallback;
+    /** Called after archive hydration but immediately before the exact workspace
+     * fingerprint probe. Lease-aware callers persist `verifying` here so a box
+     * is never observable as ready while verification is in flight. */
+    onWorkspaceRestoreVerifying?: (descriptor: WorkspaceArchiveDescriptor) => Promise<void>;
     metrics?: RuntimeMetricsHooks;
   },
 ): Promise<EstablishedSandboxSession> {
@@ -958,19 +1026,35 @@ export async function establishSandboxSessionFromEnvelope(
   //   - COLD lease re-warm (confirmDrainCold preserved a MINIMAL archive-only
   //     envelope `{ sessionState: { workspaceArchive } }` — NO sandboxId, so the
   //     warm-reattach branch must NOT try resume()-by-id; it cold-creates+hydrates).
-  const workspaceArchives = readWorkspaceArchivePairFromEnvelopeSessionState(envelopeSessionState);
-  const workspaceArchive = workspaceArchives.current;
+  const archiveState =
+    envelopeSessionState && typeof envelopeSessionState === "object"
+      ? (envelopeSessionState as {
+          workspaceArchive?: unknown;
+          workspaceArchiveMeta?: unknown;
+        })
+      : undefined;
+  // Exactly one selected revision is restored. A present archive without its
+  // revision/hash/tree descriptor is not recoverable truth and fails before any
+  // provider create. `workspaceArchivePrev` is retained for explicit future
+  // operator selection, never silently substituted in this attempt.
+  const workspaceArchiveBase64 = archiveState?.workspaceArchive;
+  const workspaceArchiveMetadata = archiveState?.workspaceArchiveMeta;
 
   // create() a FRESH box, THEN replay the persisted /workspace snapshot via
   // session.hydrateWorkspace(archive) when one rode the envelope. hydrateWorkspace
   // decodes the snapshot-ref and swaps the box for one booted from the snapshot
-  // image (restoreSnapshotFilesystem); no archive -> a clean empty box. This is the
-  // SOLE archive-replay seam, shared by the NotFound warm-reattach path AND the
-  // cold-restore branch (b) below.
-  const coldRestore = async (
-    resumeFallbackState?: unknown,
-    skipWorkspaceHydrate = false,
-  ): Promise<EstablishedSandboxSession> => {
+  // image (restoreSnapshotFilesystem). No archive is valid only for a genuinely
+  // new workspace; recovery callers select and verify an exact archive before
+  // entering this seam. This is the SOLE archive-replay path, shared by the
+  // NotFound warm-reattach path and the cold-restore branch (b) below.
+  const coldRestore = async (resumeFallbackState?: unknown): Promise<EstablishedSandboxSession> => {
+    // Parse/verify lazily: a warm resume-by-id does not consume its retained
+    // archive, so a legacy live box remains resumable. Creation/restoration is
+    // the boundary that requires complete durable metadata.
+    const workspaceArchive: VerifiedWorkspaceArchive | null = readVerifiedWorkspaceArchive(
+      workspaceArchiveBase64,
+      workspaceArchiveMetadata,
+    );
     const createStarted = Date.now();
     let restored: Awaited<ReturnType<NonNullable<typeof client.create>>>;
     try {
@@ -996,73 +1080,79 @@ export async function establishSandboxSessionFromEnvelope(
         throw createCallbackError;
       }
     }
-    // Whether an archive was ACTUALLY applied to /workspace — drives `origin`
-    // (and the worker's sandbox.box.created `hydrated` field). A clean-box
-    // fallback, a backend without hydrateWorkspace, or an all-archives-failed
-    // path leaves this false so we never report `hydrated: "archive"` for an
-    // empty workspace.
     let hydrationApplied = false;
-    if (!skipWorkspaceHydrate && (workspaceArchive || workspaceArchives.previous)) {
+    if (workspaceArchive) {
       const hydrate = (restored as { hydrateWorkspace?: (data: Uint8Array) => Promise<void> })
         .hydrateWorkspace;
-      if (typeof hydrate === "function") {
-        let hydrated = false;
-        for (const candidate of [
-          { archive: workspaceArchive, label: "current" },
-          { archive: workspaceArchives.previous, label: "previous" },
-        ]) {
-          if (!candidate.archive) {
-            continue;
-          }
+      if (typeof hydrate !== "function") {
+        await terminateCreatedSandbox(client, restored, restoredState);
+        throw new WorkspaceArchiveIntegrityError(
+          "archive_hydration_failed",
+          `sandbox backend ${client.backendId} cannot hydrate selected archive revision ${workspaceArchive.descriptor.revision}`,
+        );
+      }
+      try {
+        // hydrateWorkspace may internally replace the underlying box.
+        await hydrate.call(restored, workspaceArchive.bytes);
+      } catch (error) {
+        await terminateCreatedSandbox(client, restored, (restored as { state?: unknown }).state);
+        if (error instanceof WorkspaceArchiveIntegrityError) throw error;
+        throw new WorkspaceArchiveIntegrityError(
+          "archive_hydration_failed",
+          `failed to hydrate selected workspace archive revision ${workspaceArchive.descriptor.revision}`,
+          { retryable: true },
+        );
+      }
+      // hydrateWorkspace may replace the provider box (Modal's native snapshot
+      // restore does this). Attribute the newly-active identity immediately,
+      // before restore-state marking, fingerprint verification, or any caller
+      // can publish the box warm. The callback is the durable lease/tagging
+      // boundary; if it cannot persist the replacement, the caller fails closed
+      // and this exact replacement is terminated below.
+      const hydratedState = (restored as { state?: unknown }).state;
+      const hydratedInstanceId = readInstanceId(restored);
+      if (hydratedInstanceId && hydratedInstanceId !== established.instanceId) {
+        established = {
+          client,
+          session: restored,
+          sessionState: hydratedState ?? resumeFallbackState,
+          instanceId: hydratedInstanceId,
+          backendId: client.backendId,
+        };
+        if (opts.onSandboxCreated) {
           try {
-            // hydrateWorkspace may internally REPLACE the underlying box
-            // (restoreSnapshotFilesystem creates a replacement sandbox and terminates
-            // the placeholder), so the instanceId must be re-read AFTER.
-            await hydrate.call(restored, candidate.archive);
-            console.info(
-              `[sandbox] cold-restore hydrated workspace from ${candidate.label} archive`,
-            );
-            hydrated = true;
-            break;
-          } catch (hydrateError) {
-            console.warn(
-              `[sandbox] cold-restore failed to hydrate workspace from ${candidate.label} archive${
-                candidate.label === "current" && workspaceArchives.previous
-                  ? "; trying previous archive"
-                  : ""
-              }`,
-              hydrateError,
-            );
+            await opts.onSandboxCreated(established);
+          } catch (createCallbackError) {
+            await terminateCreatedSandbox(client, restored, hydratedState);
+            throw createCallbackError;
           }
         }
-        if (!hydrated) {
-          // If both retained archives are unusable, drop the placeholder and
-          // fall through to the same clean-box behavior as an envelope with no
-          // archive. Restore failure is fail-open; it must not strand a turn.
-          await terminateCreatedSandbox(client, restored, restoredState);
-          return await coldRestore(resumeFallbackState, true);
-        }
-        hydrationApplied = true;
-        const hydratedState = (restored as { state?: unknown }).state;
-        const hydratedInstanceId = readInstanceId(restored);
-        if (hydratedInstanceId && hydratedInstanceId !== established.instanceId) {
-          established = {
-            client,
-            session: restored,
-            sessionState: hydratedState ?? resumeFallbackState,
-            instanceId: hydratedInstanceId,
-            backendId: client.backendId,
-          };
-          if (opts.onSandboxCreated) {
-            try {
-              await opts.onSandboxCreated(established);
-            } catch (createCallbackError) {
-              await terminateCreatedSandbox(client, restored, hydratedState);
-              throw createCallbackError;
-            }
-          }
+      }
+      if (opts.onWorkspaceRestoreVerifying) {
+        try {
+          await opts.onWorkspaceRestoreVerifying(workspaceArchive.descriptor);
+        } catch (error) {
+          await terminateCreatedSandbox(client, restored, (restored as { state?: unknown }).state);
+          throw error;
         }
       }
+      try {
+        // Verification happens on the hydrated replacement before any caller
+        // may publish it warm or route an operation to it.
+        await verifyRestoredWorkspace(restored, workspaceArchive.descriptor);
+      } catch (error) {
+        await terminateCreatedSandbox(client, restored, (restored as { state?: unknown }).state);
+        if (error instanceof WorkspaceArchiveIntegrityError) throw error;
+        throw new WorkspaceArchiveIntegrityError(
+          "workspace_fingerprint_unavailable",
+          `failed to verify selected workspace archive revision ${workspaceArchive.descriptor.revision}`,
+          { retryable: true },
+        );
+      }
+      hydrationApplied = true;
+      console.info(
+        `[sandbox] cold-restore verified workspace archive revision ${workspaceArchive.descriptor.revision}`,
+      );
     }
     restoredState = (restored as { state?: unknown }).state;
     return {
@@ -1072,6 +1162,7 @@ export async function establishSandboxSessionFromEnvelope(
       instanceId: readInstanceId(restored),
       backendId: client.backendId,
       origin: hydrationApplied ? ("restored" as const) : ("created" as const),
+      ...(workspaceArchive ? { restoredArchive: workspaceArchive.descriptor } : {}),
     };
   };
 
@@ -1246,3 +1337,127 @@ export async function serializeEstablishedSandboxEnvelope(
     return null;
   }
 }
+
+const PROVIDER_IDENTITY_FIELDS = [
+  "sandboxId",
+  "instanceId",
+  "id",
+  "hostId",
+  "containerId",
+  "workspaceRootPath",
+  "agentId",
+] as const;
+
+/**
+ * Whether a replacement envelope contains a provider-resumable identity. An
+ * archive-only envelope is intentionally valid recovery metadata, but it is
+ * never proof that the newly-created provider box can be resumed or attached.
+ */
+export function hasPersistableSandboxProviderIdentity(
+  envelope: Record<string, unknown> | null | undefined,
+): envelope is Record<string, unknown> {
+  const sessionState =
+    envelope?.sessionState && typeof envelope.sessionState === "object"
+      ? (envelope.sessionState as Record<string, unknown>)
+      : null;
+  const providerState =
+    sessionState?.providerState && typeof sessionState.providerState === "object"
+      ? (sessionState.providerState as Record<string, unknown>)
+      : null;
+  return Boolean(
+    providerState &&
+    PROVIDER_IDENTITY_FIELDS.some(
+      (field) => typeof providerState[field] === "string" && providerState[field].length > 0,
+    ),
+  );
+}
+
+/** A replacement provider may not be published warm without a resumable
+ * identity. Archive-only state is retained only when the caller rolls back to
+ * cold and needs the verified workspace bytes for the next attempt. */
+export class SandboxReplacementProviderStateError extends Error {
+  readonly code = "replacement_provider_state_unpersistable" as const;
+
+  constructor(public readonly backend: string) {
+    super(
+      `sandbox backend "${backend}" replacement provider state could not be serialized; refusing to publish an attachable lease`,
+    );
+    this.name = "SandboxReplacementProviderStateError";
+  }
+}
+
+export function requirePersistableReplacementSandboxEnvelope(
+  envelope: Record<string, unknown> | null,
+  backend: string,
+): Record<string, unknown> {
+  if (!hasPersistableSandboxProviderIdentity(envelope)) {
+    throw new SandboxReplacementProviderStateError(backend);
+  }
+  return envelope;
+}
+
+const DURABLE_WORKSPACE_ARCHIVE_FIELDS = [
+  "workspaceArchive",
+  "workspaceArchiveMeta",
+  "workspaceArchivePrev",
+  "workspaceArchivePrevMeta",
+  "workspaceArchiveAt",
+] as const;
+
+function durableWorkspaceArchiveFields(
+  envelope: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+  const sessionState =
+    envelope?.sessionState && typeof envelope.sessionState === "object"
+      ? (envelope.sessionState as Record<string, unknown>)
+      : null;
+  if (
+    !sessionState ||
+    typeof sessionState.workspaceArchive !== "string" ||
+    sessionState.workspaceArchive.length === 0
+  ) {
+    return null;
+  }
+  const fields: Record<string, unknown> = {};
+  for (const key of DURABLE_WORKSPACE_ARCHIVE_FIELDS) {
+    if (sessionState[key] !== undefined && sessionState[key] !== null) {
+      fields[key] = sessionState[key];
+    }
+  }
+  return fields;
+}
+
+/**
+ * Build the only resume envelope that may be published for a newly-created
+ * replacement sandbox. Historical state contributes durable archive pointers
+ * only; it can never substitute for serialization of the replacement's provider
+ * identity. If replacement serialization is unavailable or fails, publication
+ * keeps an archive-only envelope (when one exists) or null. The new instance id
+ * remains separately fenced on the lease, while later attach/resume fails closed
+ * rather than targeting the dead provider that initiated rematerialization.
+ */
+export async function serializeReplacementSandboxEnvelope(
+  established: EstablishedSandboxSession,
+  archiveSource: Record<string, unknown> | null,
+): Promise<Record<string, unknown> | null> {
+  const serialized = await serializeEstablishedSandboxEnvelope(established);
+  const archiveFields = durableWorkspaceArchiveFields(archiveSource);
+  if (!serialized && !archiveFields) {
+    return null;
+  }
+  const serializedSessionState =
+    serialized?.sessionState && typeof serialized.sessionState === "object"
+      ? (serialized.sessionState as Record<string, unknown>)
+      : {};
+  return {
+    ...(serialized ?? {}),
+    // Never inherit a historical backend marker when the replacement could not
+    // serialize. The separately-persisted resume_backend_id and this envelope
+    // must both describe the replacement.
+    backendId: established.backendId,
+    sessionState: {
+      ...serializedSessionState,
+      ...(archiveFields ?? {}),
+    },
+  };
+}