@opengeni/runtime 4.0.1 → 4.0.3

package/src/sandbox/browser-control-client.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { posix as posixPath } from "node:path";
+import { parseBrowserFrameMetadata, type BrowserFrameMetadata } from "@opengeni/sdk";
 import {
   BROWSER_CONTROL_MAX_JSON_BYTES,
   BROWSER_CONTROL_PORT,
@@ -14,6 +15,8 @@ import {
   BrowserDownloadExportReceipt,
   BrowserDownloadExportRequest,
   BrowserDownloadListResponse,
+  BrowserDomReadRequest,
+  BrowserDomReadResponse,
   BrowserExternalAuthCommand,
   BrowserExternalAuthResult,
   BrowserObservation,
@@ -21,6 +24,7 @@ import {
   BrowserProtectedAuthFillReceipt,
   BrowserRevisionMaterialization,
   BrowserTarget,
+  BrowserTargetState,
   BrowserWorkspaceFileStageRequest,
   BrowserWorkspaceFileStageResponse,
   ComputerActionCommand,
@@ -40,6 +44,8 @@ import {
   type BrowserDownloadExportReceipt as BrowserDownloadExportReceiptValue,
   type BrowserDownloadExportRequest as BrowserDownloadExportRequestValue,
   type BrowserDownloadListResponse as BrowserDownloadListResponseValue,
+  type BrowserDomReadRequest as BrowserDomReadRequestValue,
+  type BrowserDomReadResponse as BrowserDomReadResponseValue,
   type BrowserExternalAuthCommand as BrowserExternalAuthCommandValue,
   type BrowserExternalAuthResult as BrowserExternalAuthResultValue,
   type BrowserDiagnosticKind,
@@ -48,6 +54,7 @@ import {
   type BrowserProtectedAuthFillReceipt as BrowserProtectedAuthFillReceiptValue,
   type BrowserRevisionMaterialization as BrowserRevisionMaterializationValue,
   type BrowserTarget as BrowserTargetValue,
+  type BrowserTargetState as BrowserTargetStateValue,
   type BrowserWorkspaceFileStageRequest as BrowserWorkspaceFileStageRequestValue,
   type BrowserWorkspaceFileStageResponse as BrowserWorkspaceFileStageResponseValue,
   type ComputerActionCommand as ComputerActionCommandValue,
@@ -165,6 +172,35 @@ export type ComputerControlFrame = {
   metadata: ComputerControlFrameMetadata;
 };
 
+export type BrowserControlFrame = {
+  data: Uint8Array;
+  mediaType: "image/jpeg" | "image/png";
+  metadataHeader: string;
+  metadata: BrowserFrameMetadata;
+};
+
+export type BrowserControlScreenshotOptions = {
+  fullPage?: boolean;
+  format?: "jpeg" | "png";
+  quality?: number;
+};
+
+type ExpectedBrowserFrameEvidence = {
+  browserSessionId: string;
+  controllerGeneration: string;
+  targetId: string;
+};
+
+type FrameRequest = {
+  method: "GET";
+  path: string;
+  token: string;
+  timeoutMs?: number;
+} & (
+  | { surface: "browser"; expectedFrameEvidence: ExpectedBrowserFrameEvidence }
+  | { surface: "computer"; expectedFrameEvidence: ExpectedComputerFrameEvidence }
+);
+
 export type ComputerControlFrameMetadata = {
   frameId: string;
   computerSessionId: string;
@@ -947,7 +983,17 @@ export class BrowserControlClient {
     expectedFrameEvidence: ExpectedComputerFrameEvidence;
     timeoutMs?: number;
   }): Promise<ComputerControlFrame> {
-    return await this.requestBytes(input);
+    return (await this.requestBytes({ ...input, surface: "computer" })) as ComputerControlFrame;
+  }
+
+  async requestBrowserBytesForSession(input: {
+    method: "GET";
+    path: string;
+    token: string;
+    expectedFrameEvidence: ExpectedBrowserFrameEvidence;
+    timeoutMs?: number;
+  }): Promise<BrowserControlFrame> {
+    return (await this.requestBytes({ ...input, surface: "browser" })) as BrowserControlFrame;
   }
 
   private async requestJson(
@@ -1124,15 +1170,9 @@ export class BrowserControlClient {
   }
 
   private async requestBytes(
-    input: {
-      method: "GET";
-      path: string;
-      token: string;
-      expectedFrameEvidence: ExpectedComputerFrameEvidence;
-      timeoutMs?: number;
-    },
+    input: FrameRequest,
     retryNativeEndpoint = true,
-  ): Promise<ComputerControlFrame> {
+  ): Promise<ComputerControlFrame | BrowserControlFrame> {
     const requireHostFetch = this.session.requireHostFetchController === true;
     if (this.session.resolveExposedPort && !this.session.ensureBrowserControl) {
       try {
@@ -1247,10 +1287,10 @@ export class BrowserControlClient {
       const data = await readBytes(
         this.session,
         responsePath,
-        COMPUTER_SCREENSHOT_MAX_BYTES,
+        input.surface === "browser" ? 24 * 1024 * 1024 : COMPUTER_SCREENSHOT_MAX_BYTES,
         timeoutMs,
       );
-      return computerControlFrame(data, headers, input.expectedFrameEvidence);
+      return controllerImageFrame(data, headers, input);
     } catch (error) {
       if (
         error instanceof BrowserControlRequestError ||
@@ -1432,6 +1472,104 @@ export class BrowserControlSessionClient {
     );
   }
 
+  async targetState(targetId: string): Promise<BrowserTargetStateValue> {
+    let state: BrowserTargetStateValue;
+    try {
+      state = BrowserTargetState.parse(
+        await this.parent.requestForSession({
+          method: "GET",
+          path: this.targetPath(targetId, "state"),
+          token: this.viewToken,
+        }),
+      );
+    } catch (error) {
+      // Active Connected Machines can run an older browserd during an API rollout.
+      // Only its exact unknown-route response permits the existing observation path.
+      // A missing session or target must keep its original error.
+      if (
+        !(error instanceof BrowserControlRequestError) ||
+        error.status !== 404 ||
+        error.error.code !== "resource_not_found" ||
+        error.error.message !== "route not found"
+      ) {
+        throw error;
+      }
+      const observation = await this.observe(targetId);
+      state = BrowserTargetState.parse({
+        browserSessionId: observation.browserSessionId,
+        controllerGeneration: observation.target.controllerGeneration,
+        targetId: observation.target.id,
+        targetGeneration: observation.target.targetGeneration,
+        documentGeneration: observation.target.documentGeneration,
+        frameId: observation.frameId,
+      });
+    }
+    if (
+      state.browserSessionId !== this.reference.browserSessionId ||
+      state.controllerGeneration !== this.reference.controllerGeneration ||
+      state.targetId !== targetId
+    ) {
+      throw new BrowserControlProtocolError("browser target state belongs to another binding");
+    }
+    return state;
+  }
+
+  async readDom(
+    targetId: string,
+    requestInput: BrowserDomReadRequestValue,
+  ): Promise<BrowserDomReadResponseValue> {
+    const request = BrowserDomReadRequest.parse(requestInput);
+    const result = BrowserDomReadResponse.parse(
+      await this.parent.requestForSession({
+        method: "POST",
+        path: this.targetPath(targetId, "dom-read"),
+        token: this.viewToken,
+        body: request,
+      }),
+    );
+    if (
+      result.browserSessionId !== this.reference.browserSessionId ||
+      result.controllerGeneration !== this.reference.controllerGeneration ||
+      result.targetId !== targetId ||
+      result.targetGeneration !== request.expectedTargetGeneration ||
+      result.documentGeneration !== request.expectedDocumentGeneration ||
+      result.frameId !== request.expectedFrameId ||
+      result.kind !== request.kind
+    ) {
+      throw new BrowserControlProtocolError("browser DOM read belongs to another binding");
+    }
+    return result;
+  }
+
+  async capture(
+    targetId: string,
+    options: BrowserControlScreenshotOptions = {},
+  ): Promise<BrowserControlFrame> {
+    const query = new URLSearchParams({
+      format: options.format ?? "jpeg",
+      quality: String(boundedInteger(options.quality ?? 55, 1, 100, "browser screenshot quality")),
+    });
+    if (options.format !== undefined && options.format !== "jpeg" && options.format !== "png") {
+      throw new RangeError("browser screenshot format is invalid");
+    }
+    if (options.fullPage !== undefined) {
+      if (typeof options.fullPage !== "boolean") {
+        throw new RangeError("browser screenshot fullPage is invalid");
+      }
+      query.set("fullPage", String(options.fullPage));
+    }
+    return await this.parent.requestBrowserBytesForSession({
+      method: "GET",
+      path: this.targetPath(targetId, `screenshot?${query}`),
+      token: this.viewToken,
+      expectedFrameEvidence: {
+        browserSessionId: this.reference.browserSessionId,
+        controllerGeneration: this.reference.controllerGeneration,
+        targetId: requireOpaqueId(targetId, "browser target id"),
+      },
+    });
+  }
+
   async readClipboard(): Promise<BrowserClipboardValue> {
     return BrowserClipboard.parse(
       await this.parent.requestForSession({
@@ -1840,15 +1978,9 @@ async function requestExposedController(
 
 async function requestExposedControllerBytes(
   endpoint: ExposedPortEndpoint,
-  input: {
-    method: "GET";
-    path: string;
-    token: string;
-    expectedFrameEvidence: ExpectedComputerFrameEvidence;
-    timeoutMs?: number;
-  },
+  input: FrameRequest,
   defaultTimeoutMs: number,
-): Promise<ComputerControlFrame> {
+): Promise<ComputerControlFrame | BrowserControlFrame> {
   const token = requireToken(input.token, "browser controller token");
   const timeoutMs = boundedTimeout(input.timeoutMs ?? defaultTimeoutMs);
   const streamUrl = exposedControllerUrl(endpoint, input.path);
@@ -1872,12 +2004,91 @@ async function requestExposedControllerBytes(
     throw new BrowserControlProtocolError("browser controller image response is invalid");
   }
   const declaredLength = Number(response.headers.get("content-length"));
-  if (Number.isFinite(declaredLength) && declaredLength > COMPUTER_SCREENSHOT_MAX_BYTES) {
-    await response.body?.cancel("computer frame exceeds its byte bound").catch(() => undefined);
-    throw new RangeError("computer frame exceeds its byte bound");
+  const maxBytes = input.surface === "browser" ? 24 * 1024 * 1024 : COMPUTER_SCREENSHOT_MAX_BYTES;
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    await response.body?.cancel("frame exceeds its byte bound").catch(() => undefined);
+    throw new RangeError("frame exceeds its byte bound");
+  }
+  const data = await readBoundedFrameResponse(response, maxBytes);
+  return controllerImageFrame(data, response.headers, input);
+}
+
+async function readBoundedFrameResponse(response: Response, maxBytes: number): Promise<Uint8Array> {
+  if (!response.body) throw new BrowserControlProtocolError("browser controller image is empty");
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) {
+        await reader.cancel("frame exceeds its byte bound").catch(() => undefined);
+        throw new RangeError("frame exceeds its byte bound");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
   }
-  const data = new Uint8Array(await response.arrayBuffer());
-  return computerControlFrame(data, response.headers, input.expectedFrameEvidence);
+  const data = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    data.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return data;
+}
+
+function controllerImageFrame(
+  data: Uint8Array,
+  headers: { get(name: string): string | null | undefined },
+  input: FrameRequest,
+): ComputerControlFrame | BrowserControlFrame {
+  return input.surface === "browser"
+    ? browserControlFrame(data, headers, input.expectedFrameEvidence)
+    : computerControlFrame(data, headers, input.expectedFrameEvidence);
+}
+
+function browserControlFrame(
+  data: Uint8Array,
+  headers: { get(name: string): string | null | undefined },
+  expected: ExpectedBrowserFrameEvidence,
+): BrowserControlFrame {
+  if (data.byteLength < 1 || data.byteLength > 24 * 1024 * 1024) {
+    throw new RangeError("browser frame exceeds its byte bound");
+  }
+  const get = (name: string): string | null => headers.get(name.toLowerCase()) ?? null;
+  const mediaType = get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
+  if (mediaType !== "image/jpeg" && mediaType !== "image/png") {
+    throw new BrowserControlProtocolError("browser frame media type is invalid");
+  }
+  const metadataHeader = get("x-opengeni-browser-frame");
+  if (
+    !metadataHeader ||
+    metadataHeader.length > 64 * 1024 ||
+    !/^[A-Za-z0-9_-]+$/u.test(metadataHeader)
+  ) {
+    throw new BrowserControlProtocolError("browser frame metadata is invalid");
+  }
+  let metadata: BrowserFrameMetadata;
+  try {
+    metadata = parseBrowserFrameMetadata(
+      JSON.parse(Buffer.from(metadataHeader, "base64url").toString("utf8")),
+    );
+  } catch {
+    throw new BrowserControlProtocolError("browser frame metadata is invalid");
+  }
+  if (
+    metadata.browserSessionId !== expected.browserSessionId ||
+    metadata.controllerGeneration !== expected.controllerGeneration ||
+    metadata.targetId !== expected.targetId ||
+    metadata.mediaType !== mediaType
+  ) {
+    throw new BrowserControlProtocolError("browser frame evidence does not match its request");
+  }
+  return { data, mediaType, metadataHeader, metadata };
 }
 
 function computerControlFrame(
@@ -2764,7 +2975,11 @@ async function readBytes(
   timeoutMs: number,
 ): Promise<Uint8Array> {
   const privatePath = absolutePrivatePath(path, "browser private binary response path");
-  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > COMPUTER_SCREENSHOT_MAX_BYTES) {
+  if (
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 1 ||
+    maxBytes > Math.max(24 * 1024 * 1024, COMPUTER_SCREENSHOT_MAX_BYTES)
+  ) {
     throw new RangeError("browser private binary response limit is invalid");
   }
   const sizeMarker = `OPENGENI_BROWSER_PRIVATE_SIZE_${randomUUID()}`;
@@ -2783,7 +2998,7 @@ async function readBytes(
     "browser private binary response size",
   );
   if (size < 1 || size > maxBytes) {
-    throw new RangeError("computer frame exceeds its byte bound");
+    throw new RangeError("frame exceeds its byte bound");
   }
   const chunks: Buffer[] = [];
   for (let offset = 0; offset < size; offset += PRIVATE_READ_CHUNK_BYTES) {

package/src/sandbox/index.ts

@@ -175,7 +175,7 @@ export {
   ensureModalRegistryImage,
   deleteModalCheckpointSnapshot,
   inspectModalSandboxLifecycle,
-  isModalTaskExecStartDnsResolutionError,
+  isModalTaskExecStartPreDispatchUnavailableError,
   modalSessionMatchesCheckpointProviderBinding,
   modalSandboxAttributionEnvironment,
   modalSandboxAttributionTags,
@@ -303,6 +303,8 @@ export {
   provisionBrowserControlClient,
   validateComputerControlFrameEvidence,
   type BrowserControlPlacementSession,
+  type BrowserControlScreenshotOptions,
+  type BrowserControlFrame,
   type BrowserStateDownloadGrant,
   type BrowserStateUploadGrant,
   type BrowserViewGrant,

package/src/sandbox/providers/modal-command-control.ts

@@ -20,6 +20,7 @@ import {
 } from "./modal-legacy-command-control";
 import {
   ModalCommandRouterWire,
+  ModalCommandStartPreDispatchUnavailableError,
   ModalCommandStartRejectedError,
 } from "./modal-command-router-wire";
 
@@ -236,7 +237,12 @@ export class ModalCommandControl {
       // A client-chosen router id remains the only possible invocation. The
       // supervisor is idle, so an ambiguous launch never ran user code. Retain
       // the descriptor and reconcile that id; do not replay the start.
-      if (!supervision || error instanceof ModalCommandStartRejectedError) throw error;
+      if (
+        !supervision ||
+        error instanceof ModalCommandStartRejectedError ||
+        error instanceof ModalCommandStartPreDispatchUnavailableError
+      )
+        throw error;
     }
     return command;
   }

package/src/sandbox/providers/modal-command-router-wire.ts

@@ -47,6 +47,35 @@ export class ModalCommandStartRejectedError extends ProviderCommandStartRejected
   }
 }
 
+/** Only a local channel-readiness failure BEFORE TaskExecStart is issued can
+ * prove that start was never dispatched. RPC status/details, even if they look
+ * like a DNS resolver error, can originate from an accepting server. */
+export class ModalCommandStartPreDispatchUnavailableError extends Error {
+  private constructor(cause: Error) {
+    super("Modal command router was not ready before Start dispatch", { cause });
+    this.name = "ModalCommandStartPreDispatchUnavailableError";
+  }
+
+  static async ensureReady(client: Client, signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted();
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const finish = (error?: Error) => {
+        if (settled) return;
+        settled = true;
+        signal?.removeEventListener("abort", abort);
+        if (signal?.aborted) reject(signal.reason);
+        else if (error) reject(new ModalCommandStartPreDispatchUnavailableError(error));
+        else resolve();
+      };
+      const abort = () => finish();
+      signal?.addEventListener("abort", abort, { once: true });
+      client.waitForReady(Date.now() + 5_000, finish);
+      if (signal?.aborted) abort();
+    });
+  }
+}
+
 export type ModalRouterIdentity = { taskId: string; execId: string };
 export type ModalRouterAccess = { url: string; jwt: string };
 export type ModalRouterStart = ModalRouterIdentity & {
@@ -76,16 +105,21 @@ export class ModalCommandRouterWire {
   private readonly client: Client;
   private readonly metadata: Metadata;
   private closed = false;
-
   constructor(access: ModalRouterAccess, trustedRoots?: Buffer) {
     const url = new URL(access.url);
     if (url.protocol !== "https:" || url.username || url.password || !access.jwt)
       throw new Error("Modal command router requires authenticated TLS");
-    this.client = new Client(url.host, credentials.createSsl(trustedRoots), {
-      "grpc.max_receive_message_length": maxWireBytes,
-      "grpc.max_send_message_length": maxWireBytes,
-      "grpc.enable_retries": 0,
-    });
+    // URL.host elides HTTPS's default :443; use the actual normalized gRPC
+    // target for both the resolver and the authenticated TLS transport.
+    this.client = new Client(
+      `${url.hostname}:${url.port || "443"}`,
+      credentials.createSsl(trustedRoots),
+      {
+        "grpc.max_receive_message_length": maxWireBytes,
+        "grpc.max_send_message_length": maxWireBytes,
+        "grpc.enable_retries": 0,
+      },
+    );
     this.metadata = new Metadata();
     this.metadata.set("authorization", `Bearer ${access.jwt}`);
   }
@@ -127,6 +161,13 @@ export class ModalCommandRouterWire {
   }
 
   async start(request: ModalRouterStart, signal?: AbortSignal): Promise<void> {
+    if (this.closed) throw new Error("Modal command router is closed");
+    try {
+      await ModalCommandStartPreDispatchUnavailableError.ensureReady(this.client, signal);
+    } catch (error) {
+      if (this.closed) throw new Error("Modal command router is closed", { cause: error });
+      throw error;
+    }
     try {
       await this.unary(
         "TaskExecStart",

package/src/sandbox/providers/modal.ts

@@ -15,6 +15,8 @@ import { CAPABILITY_DESCRIPTORS } from "../capabilities";
 import { SandboxChannelAService, type ChannelASession } from "../channel-a";
 import { installModalCommandSession } from "./modal-command-session";
 import { ModalCommandControl } from "./modal-command-control";
+import { ModalCommandStartPreDispatchUnavailableError } from "./modal-command-router-wire";
+import { isRoutingMutationOutcomeUnknownError } from "../routing/routing-session";
 import type { ModalClient } from "modal";
 import { ModalProcessObservationUnavailableError, SandboxConfigError } from "../errors";
 export { ModalProcessObservationUnavailableError } from "../errors";
@@ -207,9 +209,6 @@ const MODAL_EXEC_STDIN_WRITE_PATH =
   "/modal.task_command_router.TaskCommandRouter/TaskExecStdinWrite";
 const MODAL_EXEC_ALREADY_COMPLETED_DETAILS =
   /^Exec has already completed; stdin is no longer accepting writes(?: \(Error code: [A-Z0-9]+\))?$/;
-const MODAL_TASK_EXEC_START_PATH = "/modal.task_command_router.TaskCommandRouter/TaskExecStart";
-const MODAL_TASK_EXEC_START_DNS_RESOLUTION_DETAILS =
-  /^Name resolution failed for target dns:task-[a-z0-9]+\.w\.modal\.host:443$/;
 const MODAL_TASK_EXEC_START_ERROR_MAX_DEPTH = 8;
 const MODAL_TASK_EXEC_START_ERROR_MAX_NODES = 64;
 const MODAL_TASK_EXEC_START_ERROR_MAX_AGGREGATE_ERRORS = 32;
@@ -234,24 +233,13 @@ function hasContradictoryModalHttpStatus(record: Record<string, unknown>): boole
   return values.some((value) => modalHttpStatus(value) !== null);
 }
 
-function isModalTaskExecStartDnsResolutionLeaf(record: Record<string, unknown>): boolean {
-  return (
-    record.name === "ClientError" &&
-    record.path === MODAL_TASK_EXEC_START_PATH &&
-    (record.code === 14 || record.code === "UNAVAILABLE") &&
-    typeof record.details === "string" &&
-    MODAL_TASK_EXEC_START_DNS_RESOLUTION_DETAILS.test(record.details)
-  );
-}
-
 /**
- * Modal exhausted its own retries before failing to resolve the exact command
- * router DNS name, so TaskExecStart never connected and replay is safe. Keep
- * this fail-closed across Agents SDK wrappers: every reachable structural leaf
- * must be that exact ClientError with no HTTP status metadata, and any incomplete
- * or mixed graph is rejected.
+ * Only the native client's pre-dispatch readiness gate proves Start was not
+ * sent. Server-controlled gRPC/SDK status and DNS-looking details prove nothing.
+ * Any retained or outcome-unknown routing boundary vetoes recovery even when
+ * it contains a genuine pre-dispatch error among its causes.
  */
-export function isModalTaskExecStartDnsResolutionError(error: unknown): boolean {
+export function isModalTaskExecStartPreDispatchUnavailableError(error: unknown): boolean {
   const pending: Array<{ depth: number; value: unknown }> = [{ depth: 0, value: error }];
   const seen = new WeakSet<object>();
   let inspected = 0;
@@ -270,8 +258,16 @@ export function isModalTaskExecStartDnsResolutionError(error: unknown): boolean
     let nested: unknown[];
     try {
       const record = current.value as Record<string, unknown>;
+      if (isRoutingMutationOutcomeUnknownError(current.value)) return false;
       if (hasContradictoryModalHttpStatus(record)) return false;
 
+      // This instance is created only by the client's readiness gate before
+      // Start dispatch; an RPC's own status or details never enters this path.
+      if (current.value instanceof ModalCommandStartPreDispatchUnavailableError) {
+        matchingLeaves += 1;
+        continue;
+      }
+
       nested = [];
       for (const key of ["cause", "error"] as const) {
         const value = record[key];
@@ -290,11 +286,7 @@ export function isModalTaskExecStartDnsResolutionError(error: unknown): boolean
         nested.push(...errors);
       }
 
-      if (nested.length === 0) {
-        if (!isModalTaskExecStartDnsResolutionLeaf(record)) return false;
-        matchingLeaves += 1;
-        continue;
-      }
+      if (nested.length === 0) return false;
     } catch {
       return false;
     }

package/src/sandbox/routing/routing-session.ts

@@ -28,6 +28,7 @@
 // `@opengeni/db`.
 
 import type { ExposedPortEndpoint } from "../stream-port";
+import { ModalCommandStartPreDispatchUnavailableError } from "../providers/modal-command-router-wire";
 import { isDeepStrictEqual } from "node:util";
 import {
   withProviderCommandHandle,
@@ -1687,7 +1688,8 @@ export class RoutingSandboxSession implements RoutableBackendSession {
       } catch (error) {
         if (reservedProcess) {
           if (
-            error instanceof ProviderCommandStartRejectedError &&
+            (error instanceof ProviderCommandStartRejectedError ||
+              error instanceof ModalCommandStartPreDispatchUnavailableError) &&
             reservedProcess.providerCommand?.kind === "modal-router-v1"
           ) {
             const persistence = this.deps.providerCommandPersistence?.(reservedProcess);
@@ -1697,7 +1699,7 @@ export class RoutingSandboxSession implements RoutableBackendSession {
               } catch (cause) {
                 throw new RoutingMutationOutcomeUnknownError(
                   op,
-                  "Never-started provider rejection could not settle its exact reservation",
+                  "Never-started provider call could not settle its exact reservation",
                   { cause, retainedProcess: reservedProcess },
                 );
               }