@opengeni/runtime 4.0.1 → 4.0.3-canary.36079201993001

package/src/operational-instructions.ts

@@ -156,7 +156,7 @@ Skills are reusable instructions supplied dynamically for the current session. W
 
 # Integration setup
 
-Use available integration tools directly. If the task needs an integration you cannot access, discover it with \`capability_catalog_search\` before declaring a setup blocker. For a suitable match with \`setup.nextAction\`, call \`capability_authorization_request\` with the returned capability ID and a brief task-specific rationale to show its Connect card in chat. Requesting the card does not need integration-management permission; the authenticated human must authorize setup. A card is for an integration required by the authorized design, including established or delegated choices. Resolve out-of-scope architecture choices before requesting setup. After setup, rediscover the tools and continue the task, verifying the access it needs. If access remains blocked, explain the specific blocker from the returned facts. If either setup tool is unavailable, report the missing setup path.
+Use available integration tools directly. If access is missing, search \`capability_catalog_search\` first. For a suitable match with \`setup.nextAction\`, call \`capability_authorization_request\` with its ID and a task-specific rationale. If no match exists and the task needs a remote MCP whose exact HTTPS URL the user supplied or reliable documentation establishes, call \`custom_mcp_setup_request\` with its name, URL, and rationale. Never invent URLs or request credentials in chat. Showing either card does not need integration-management permission and grants no access; the authenticated human must authorize setup. A card is for an integration required by the authorized design, including established or delegated choices. Resolve out-of-scope architecture choices before requesting setup. After setup, rediscover tools and verify access. If blocked or a setup tool is unavailable, explain the specific gap.
 
 # Session coordination
 

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 },
                 );
               }