@opengeni/api-router 0.30.3 → 1.0.0

package/src/routes/browser-sessions.ts

@@ -1,11 +1,18 @@
+import {
+  assertEphemeralBrowserCreateEnabled,
+  ephemeralBrowserPartition,
+} from "../browser-ephemeral";
 import { randomUUID } from "node:crypto";
 import {
   environmentsEncryptionKeyBytes,
   resolveFirstPartyDelegationSecret,
   resolveStreamTokenSecret,
+  sandboxWarmRateMicrosPerSecond,
 } from "@opengeni/config";
 import {
   BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX,
+  EPHEMERAL_CHROMIUM_DRIVER_ID,
+  browserSessionStorageMode,
   BROWSER_CONTROL_WEBSOCKET_PROTOCOL,
   BROWSER_CONTROL_PORT,
   BROWSER_CONTROL_PROTOCOL_VERSION,
@@ -20,6 +27,8 @@ import {
   BrowserDownloadSaveRequest,
   BrowserDownloadSaveResponse,
   BrowserDownloadListResponse,
+  BrowserDomReadRequest,
+  BrowserDomReadResponse,
   BrowserExternalAuthCommand,
   BrowserOpenTargetRequest,
   BrowserObservation,
@@ -31,6 +40,7 @@ import {
   BrowserSessionListResponse,
   BrowserSessionMutationResponse,
   BrowserTargetListResponse,
+  BrowserTargetState,
   CreateBrowserSessionRequest,
   ExternalAuthInteractiveRequest,
   ExternalAuthInteractiveResponse,
@@ -59,6 +69,7 @@ import {
   type SiteAuthAuthority,
 } from "@opengeni/contracts";
 import {
+  getSessionAuthorityEpoch,
   acquireLease,
   activateBrowserSession,
   ATTACHED_BROWSER_SESSION_CAPABILITIES,
@@ -74,6 +85,7 @@ import {
   BrowserSessionNotFoundError,
   BrowserSessionOperationConflictError,
   BrowserSessionStateError,
+  SandboxPaidComputeAdmissionError,
   completeBrowserSessionEnd,
   completeExternalAuth,
   completeBrowserDownloadSave,
@@ -87,6 +99,8 @@ import {
   dispatchExternalAuth,
   dispatchProtectedAuthFill,
   failBrowserSessionOperation,
+  failPreparedBrowserSessionEnd,
+  failPreparedBrowserSessionSuspend,
   failBrowserSessionResume,
   failBrowserSessionResumePreparation,
   failBrowserSessionSuspension,
@@ -95,10 +109,11 @@ import {
   findBrowserDownloadSave,
   getBrowserSessionControlRecord,
   getComputerSessionControlRecord,
+  getBrowserIdentity,
   getBrowserPrivateCheckpointAuthority,
   getAttachedBrowserDevice,
   getBrowserRevisionArtifactAuthority,
-  getEnrollment,
+  getLiveEnrollmentConnection,
   getExternalAuthInteractiveContext,
   getFilesForSubject,
   getFileUpload,
@@ -114,6 +129,7 @@ import {
   listBrowserSessions,
   listAttachedBrowserDevices,
   prepareBrowserSessionCreate,
+  markEphemeralBrowserSessionLost,
   prepareExternalAuth,
   prepareBrowserDownloadSave,
   prepareBrowserSessionEnd,
@@ -131,6 +147,7 @@ import {
   touchBrowserSessionController,
   verifyAuthRun,
   settleBrowserDownloadSaveFailure,
+  terminalizeStaleConnectedInteractionPlacement,
   type BrowserSessionControlRecord,
   type BrowserPrivateCheckpointAuthority,
   type BrowserRevisionArtifactAuthority,
@@ -142,6 +159,7 @@ import {
   recordWorkspaceUsage,
   requireLimit,
   relayConfigFromSettings,
+  resolveSessionSandboxRuntime,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   type ApiRouteDeps,
@@ -158,16 +176,21 @@ import {
   buildStreamUrl,
   exposedPortEndpointFromUrl,
   buildSelfhostedBackendSession,
+  ensureDisplayStack,
   mintStreamToken,
   NatsControlRpc,
   NatsOpStreamTransport,
   provisionBrowserControlClient,
+  renewSandboxProviderExpiration,
   type BrowserControlPlacementSession,
+  type BrowserControlScreenshotOptions,
+  type BrowserControlFrame,
   type PlacementBrowserStateCaptureReceipt,
   type PlacementBrowserNetworkRoute,
   type PlacementBrowserTransport,
   type RestorePlacementBrowserStateInput,
 } from "@opengeni/runtime/sandbox";
+import { retryWhileMissing } from "@opengeni/storage";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
@@ -176,8 +199,17 @@ import {
   deriveBrowserNetworkRouteAuthorityDigest,
   deriveBrowserSessionControllerTokens,
   deriveBrowserViewGrantToken,
+  deriveComputerSessionControllerTokens,
 } from "../browser-controller-authority";
-import { withCachedController } from "../controller-data-plane";
+import {
+  controllerCacheAllowsHostFetch,
+  controllerCachedUrlIsUsable,
+  shouldPersistControllerDataPlaneUrl,
+  isRetryableControllerTransport,
+  withCachedController,
+  withControllerTransportRecovery,
+} from "../controller-data-plane";
+import { filterInteractionSessionsForGrant } from "../interaction-agent-access";
 import { withInteractionHolderHeartbeat } from "../interaction-holder-heartbeat";
 import {
   browserStateArtifactAad,
@@ -192,7 +224,13 @@ import {
   resolveProtectedAuthFieldValues,
 } from "../browser-auth-broker";
 import { managedNetworkRouteForPlacement } from "../browser-network-route";
-import { allowedCorsOrigin } from "../http/cors";
+import { validateInteractionRequestOrigin } from "../http/cors";
+import { ApiHttpError } from "../http/api-error";
+import { interactionControlApiError } from "../http/interaction-control-error";
+import {
+  createInteractionFrameProxyAttachment,
+  placementUsesInteractionFrameProxy,
+} from "../interaction-frame-proxy";
 import {
   observeAuthMutation,
   observeBrowserActionResult,
@@ -201,6 +239,7 @@ import {
 } from "../interaction-metrics";
 import { withChannelA, withChannelARead, type ChannelAOperation } from "../sandbox/channel-a";
 import { sanitizeFilename } from "./files";
+import { USER_CONTENT_SECURITY_HEADERS } from "../http/user-content";
 
 const BROWSER_DRIVER_ID = "opengeni.cdp.v1";
 const LIGHTPANDA_DRIVER_ID = "opengeni.lightpanda.cdp.v1";
@@ -265,13 +304,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
   app.get("/v1/workspaces/:workspaceId/browser-sessions", async (context) => {
     const workspaceId = context.req.param("workspaceId") ?? "";
     const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:read");
+    const listed = await listBrowserSessions(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
     return context.json(
-      BrowserSessionListResponse.parse(
-        await listBrowserSessions(deps.db, {
-          accountId: grant.accountId,
-          workspaceId,
-        }),
-      ),
+      BrowserSessionListResponse.parse({
+        ...listed,
+        sessions: await filterInteractionSessionsForGrant(deps, grant, listed.sessions),
+      }),
     );
   });
 
@@ -298,10 +339,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     const request = await parseJsonBody(context, CreateBrowserSessionRequest);
     const startedAtMs = performance.now();
     await authorizeSourceSession(deps, grant, request.sessionId, "session.control");
-    const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+    const origin = requestOrigin(context, deps.settings);
     const authority = browserAuthorityRoot(deps);
+    let prepared: Awaited<ReturnType<typeof prepareBrowserSessionCreate>> | null = null;
 
     try {
+      assertEphemeralBrowserCreateEnabled(
+        request,
+        deps.settings.experimentalBrowserContextPoolEnabled,
+      );
       const existing = await findBrowserSessionControlRecordByOperation(deps.db, {
         accountId: grant.accountId,
         workspaceId,
@@ -313,7 +359,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         );
       }
       if (existing) assertCreateReplay(request, existing.session);
-      let prepared = existing
+      prepared = existing
         ? await prepareBrowserSessionCreate(
             deps.db,
             browserCreateInput(grant, workspaceId, request, existing.session.placement),
@@ -325,6 +371,20 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         return context.json(parsed, 200);
       }
 
+      // Reject an unavailable explicit identity before acquiring or waking the
+      // browser placement. prepareBrowserSessionCreate repeats this check in its
+      // transaction, so an archive racing this preflight is still fenced.
+      if (!existing && request.identityId) {
+        const identity = await getBrowserIdentity(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          identityId: request.identityId,
+        });
+        if (identity.status !== "active") {
+          throw new BrowserIdentityStateError("BrowserIdentity is archived");
+        }
+      }
+
       const sourceSession = await requireSourceSession(deps, workspaceId, request.sessionId);
       const response = await withBrowserPlacement(
         sourceSession,
@@ -401,12 +461,6 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             });
             const preparedSession = prepared.session;
             const controllerGeneration = requireOperationGeneration(record);
-            const linkedComputer = await requireLinkedComputerBinding(
-              deps,
-              grant,
-              prepared.session,
-              placement,
-            );
             const adminToken = deriveBrowserControllerAdminToken({
               rootSecret: authority,
               accountId: grant.accountId,
@@ -432,8 +486,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                 placement,
                 adminToken,
                 origin,
-                async (client) =>
-                  await withInteractionHolderHeartbeat(
+                async (client) => {
+                  const linkedComputer = await ensureLinkedComputerController(
+                    deps,
+                    grant,
+                    preparedSession,
+                    placement,
+                    client,
+                  );
+                  return await withInteractionHolderHeartbeat(
                     deps,
                     {
                       grant,
@@ -444,20 +505,32 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                       resourceId: preparedSession.id,
                       controllerGeneration,
                     },
-                    async () =>
-                      await client.createSession({
+                    async () => {
+                      await ensureHeadedBrowserDisplayStack(
+                        placement.session,
+                        preparedSession.headless,
+                        linkedComputer !== null,
+                      );
+                      return await client.createSession({
                         browserSessionId: preparedSession.id,
                         controllerGeneration,
                         tokenGeneration: record.tokenGeneration,
                         ...tokens,
                         headed: !preparedSession.headless,
-                        transport: browserRuntimeTransport(preparedSession, placement.transport),
+                        transport: browserRuntimeTransport(
+                          preparedSession,
+                          placement.transport,
+                          placement.placementInstanceId,
+                          authority,
+                        ),
                         ...(linkedComputer ? { linkedComputer } : {}),
                         ...(networkRoute ? { networkRoute } : {}),
                         ...(request.initialUrl ? { initialUrl: request.initialUrl } : {}),
                         ...(restore ? { restore } : {}),
-                      }),
-                  ),
+                      });
+                    },
+                  );
+                },
               );
               await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
                 () => placement,
@@ -519,6 +592,18 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         parsed.operation.state === "completed" && !parsed.operation.replayed ? 201 : 200,
       );
     } catch (error) {
+      if (prepared) {
+        // The operation lock fences a concurrent dispatch. Once a controller
+        // binding exists, retain its exact receipt for physical reconciliation.
+        await failBrowserSessionOperation(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          operationId: request.operationId,
+          browserSessionId: prepared.session.id,
+          onlyIfPreparedCreate: true,
+          error: interactionFailure(error),
+        }).catch(() => undefined);
+      }
       throw browserRouteError(error);
     }
   });
@@ -908,6 +993,82 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     },
   );
 
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/state",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.targetState(targetId),
+      );
+      return context.json(BrowserTargetState.parse(result));
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/dom-read",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const request = await parseJsonBody(context, BrowserDomReadRequest);
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.readDom(targetId, request),
+      );
+      return context.json(BrowserDomReadResponse.parse(result));
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/screenshot",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const captureOptions = parseBrowserScreenshotOptions(new URL(context.req.url).searchParams);
+      const frame = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient, record }) => {
+          if (!record.session.capabilities.screenshots) {
+            throw new BrowserControlUnsupportedError(
+              "This browser engine does not render page screenshots; use semantic observation",
+            );
+          }
+          try {
+            return await sessionClient.capture(targetId, captureOptions);
+          } catch (error) {
+            throw browserScreenshotError(error);
+          }
+        },
+      );
+      return browserScreenshotResponse(frame);
+    },
+  );
+
   app.post(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/actions",
     async (context) => {
@@ -1663,7 +1824,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         context,
         "stream:view",
       );
-      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+      const origin = requestOrigin(context, deps.settings);
       const request = await parseJsonBody(context, BrowserSessionAttachmentRequest);
       const result = await withActiveBrowserController(
         context,
@@ -1705,7 +1866,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             browserSessionId,
             controllerGeneration: binding.controllerGeneration,
           };
-          await client.createViewGrant(reference, {
+          const viewGrant = await client.createViewGrant(reference, {
             grantId,
             token,
             expiresAt,
@@ -1719,6 +1880,18 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           });
           const stream = relayed
             ? await (async () => {
+                // 0281: stamp the authenticated viewer subject and the live
+                // session authority epoch into the relay stream token.
+                const relayAuthorityEpoch = await getSessionAuthorityEpoch(deps.db, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  sessionId: record.sourceSessionId,
+                });
+                if (relayAuthorityEpoch === null) {
+                  throw new BrowserControlUnsupportedError(
+                    "stream authority is unavailable for this session",
+                  );
+                }
                 const relayToken = await mintStreamToken(relaySecret!, {
                   workspaceId,
                   sessionId: record.sourceSessionId,
@@ -1726,6 +1899,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   leaseEpoch: record.tokenGeneration,
                   port: relayed.channel.port,
                   ttlSeconds: request.expiresInSeconds,
+                  subjectId: grant.subjectId,
+                  authorityEpoch: relayAuthorityEpoch,
                 });
                 return {
                   kind: "relay" as const,
@@ -1740,19 +1915,53 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   },
                 };
               })()
-            : {
-                kind: "direct_websocket" as const,
-                url: await client.frameStreamUrl(reference, request.targetId, request.stream),
-                protocols: [
+            : await (async () => {
+                const protocols = [
                   BROWSER_CONTROL_WEBSOCKET_PROTOCOL,
                   `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
-                ],
-              };
+                ] as const;
+                const upstreamUrl = await client.frameStreamUrl(
+                  reference,
+                  request.targetId,
+                  request.stream,
+                );
+                const attachment = placementUsesInteractionFrameProxy(placement.lease?.backend, {
+                  openSandboxSignedEndpoints: deps.settings.openSandboxSignedEndpoints,
+                  ...(typeof deps.settings.openSandboxInteractionFrameProxy === "boolean"
+                    ? {
+                        openSandboxInteractionFrameProxy:
+                          deps.settings.openSandboxInteractionFrameProxy,
+                      }
+                    : {}),
+                })
+                  ? createInteractionFrameProxyAttachment({
+                      requestUrl: context.req.url,
+                      publicBaseUrl: deps.settings.publicBaseUrl,
+                      webBaseUrl: deps.settings.webBaseUrl,
+                      forwardedProto: context.req.header("x-forwarded-proto"),
+                      forwardedHost:
+                        context.req.header("x-forwarded-host") ?? context.req.header("host"),
+                      rootSecret,
+                      upstreamUrl,
+                      upstreamProtocols: protocols,
+                      origin,
+                      expiresAt,
+                    })
+                  : { url: upstreamUrl, protocols };
+                return {
+                  kind: "direct_websocket" as const,
+                  ...attachment,
+                };
+              })();
           return BrowserSessionAttachment.parse({
             browserSessionId,
             controllerGeneration: binding.controllerGeneration,
             targetId: request.targetId,
             stream,
+            ...(viewGrant.fencedInputBatches === true ? { fencedInputBatches: true } : {}),
+            ...(viewGrant.focusedInputObservations === true
+              ? { focusedInputObservations: true }
+              : {}),
             expiresAt,
           });
         },
@@ -1958,7 +2167,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
       const startedAtMs = performance.now();
-      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+      const origin = requestOrigin(context, deps.settings);
+      let preparedForDispatch = false;
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2010,6 +2220,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           return context.json(parsed, 200);
         }
 
+        preparedForDispatch = true;
+
         const record = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
           workspaceId,
@@ -2171,6 +2383,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         observeLifecycleResult(deps.observability, startedAtMs, parsed);
         return context.json(parsed, 200);
       } catch (error) {
+        if (preparedForDispatch) {
+          await failPreparedBrowserSessionSuspend(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+            operationId: request.operationId,
+            error: interactionFailure(error),
+          });
+        }
         throw browserRouteError(error);
       }
     },
@@ -2184,7 +2405,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
       const startedAtMs = performance.now();
-      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+      const origin = requestOrigin(context, deps.settings);
       let restore: RestorePlacementBrowserStateInput | null = null;
       try {
         let before = await getBrowserSessionControlRecord(deps.db, {
@@ -2303,12 +2524,6 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               throw error;
             });
             const controllerGeneration = requireOperationGeneration(record);
-            const linkedComputer = await requireLinkedComputerBinding(
-              deps,
-              grant,
-              prepared.session,
-              placement,
-            );
             const adminToken = deriveBrowserControllerAdminToken({
               rootSecret: authority,
               accountId: grant.accountId,
@@ -2332,6 +2547,13 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               ...(origin ? { allowedOrigins: [origin] } : {}),
             });
             try {
+              const linkedComputer = await ensureLinkedComputerController(
+                deps,
+                grant,
+                prepared.session,
+                placement,
+                client,
+              );
               await withInteractionHolderHeartbeat(
                 deps,
                 {
@@ -2343,8 +2565,13 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   resourceId: browserSessionId,
                   controllerGeneration,
                 },
-                async () =>
-                  await client.createSession({
+                async () => {
+                  await ensureHeadedBrowserDisplayStack(
+                    placement.session,
+                    prepared.session.headless,
+                    linkedComputer !== null,
+                  );
+                  return await client.createSession({
                     browserSessionId,
                     controllerGeneration,
                     tokenGeneration: record.tokenGeneration,
@@ -2354,7 +2581,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                     ...(linkedComputer ? { linkedComputer } : {}),
                     ...(networkRoute ? { networkRoute } : {}),
                     restore: restore!,
-                  }),
+                  });
+                },
               );
             } catch (error) {
               if (!isDefiniteBrowserControllerFailure(error)) throw error;
@@ -2426,7 +2654,12 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
       const startedAtMs = performance.now();
-      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+      const origin = requestOrigin(context, deps.settings);
+      let endPreparation: {
+        restoreLifecycle: BrowserSessionValue["lifecycle"];
+        restoreFailureCode: string | null;
+        expectedControllerGeneration: string | null;
+      } | null = null;
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2441,6 +2674,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           browserSessionId,
           operationId: request.operationId,
           actorSubjectId: grant.subjectId,
+          expectedLifecycle: before.session.lifecycle,
+          expectedFailureCode: before.session.failureCode,
+          expectedControllerGeneration: before.session.controller?.controllerGeneration ?? null,
         });
         if (isTerminalOperation(prepared.operation.state)) {
           if (prepared.operation.state === "completed") {
@@ -2456,6 +2692,13 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           observeLifecycleResult(deps.observability, startedAtMs, parsed);
           return context.json(parsed, 200);
         }
+        if (before.session.lifecycle !== "ending") {
+          endPreparation = {
+            restoreLifecycle: before.session.lifecycle,
+            restoreFailureCode: before.session.failureCode,
+            expectedControllerGeneration: before.session.controller?.controllerGeneration ?? null,
+          };
+        }
 
         const record = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2549,6 +2792,16 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         observeLifecycleResult(deps.observability, startedAtMs, parsed);
         return context.json(parsed, 200);
       } catch (error) {
+        if (endPreparation) {
+          await failPreparedBrowserSessionEnd(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+            operationId: request.operationId,
+            ...endPreparation,
+            error: interactionFailure(error),
+          });
+        }
         throw browserRouteError(error);
       }
     },
@@ -2562,6 +2815,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     operation: ChannelAOperation,
     waitSignal: AbortSignal,
     callback: (placement: BrowserPlacement) => Promise<T>,
+    allowOperationReplay = true,
   ): Promise<T> {
     if (expectedPlacement?.kind === "attached_device") {
       waitSignal.throwIfAborted();
@@ -2573,18 +2827,29 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       if (device.state !== "connected") {
         throw new BrowserSessionStateError("Attached browser is disconnected");
       }
-      const enrollment = await getEnrollment(
+      const enrollment = await getLiveEnrollmentConnection(
         deps.db,
         sourceSession.workspaceId,
         device.enrollmentId,
       );
-      if (!enrollment || enrollment.status !== "active") {
+      if (!enrollment || enrollment.status !== "active" || !enrollment.connectionInstanceId) {
         throw new BrowserSessionStateError("Attached browser machine is unavailable");
       }
-      assertPlacementInstance(expectedPlacementInstanceId, device.connectionGeneration);
+      if (!enrollment.workspaceRoot) {
+        throw new BrowserSessionStateError(
+          "Attached browser machine has not reported an absolute workspace root",
+        );
+      }
+      const placementInstanceId = attachedEndPlacementInstanceId(
+        operation,
+        expectedPlacementInstanceId,
+        device.connectionGeneration,
+      );
       const built = await buildSelfhostedBackendSession({
         workspaceId: sourceSession.workspaceId,
         agentId: device.enrollmentId,
+        connectionInstanceId: enrollment.connectionInstanceId,
+        workspaceRoot: enrollment.workspaceRoot,
         relay: relayConfigFromSettings(deps.settings),
         controlRpcFactory: () => new NatsControlRpc(async () => deps.bus.getRequestConnection()),
         // Browser-profile generation is the physical controller fence. Epoch 0
@@ -2593,6 +2858,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         epoch: 0,
         timeoutMs: deps.settings.sandboxSelfhostedControlTimeoutMs,
         execTimeoutMs: deps.settings.sandboxSelfhostedExecTimeoutMs,
+        operationResourcePolicy: enrollment.operationPolicy,
+        operationResourcePolicySupported:
+          enrollment.agentCapabilities.operationResourcePolicy === true,
+        operationCpuQuotaSupported: enrollment.agentCapabilities.operationCpuQuota === true,
+        transactionalFsWriteSupported: enrollment.agentCapabilities.transactionalFsWrite === true,
         ...(deps.settings.agentOpStreamEnabled === true &&
         enrollment.opStream === true &&
         deps.bus.getOpStreamConnection
@@ -2609,13 +2879,13 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       return await callback({
         placement: expectedPlacement,
         controllerHostSandboxGroupId: null,
-        placementInstanceId: device.connectionGeneration,
+        placementInstanceId,
         session: built.session as unknown as BrowserControlPlacementSession,
         lease: null,
         transport: {
           kind: "attached_chrome",
           deviceId: device.id,
-          connectionGeneration: device.connectionGeneration,
+          connectionGeneration: placementInstanceId,
           browserName: device.browserName,
           browserVersion: device.browserVersion,
         },
@@ -2638,6 +2908,12 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         waitSignal,
         operation,
         retryControllerTransport: operation === "browser.read" || operation === "browser.action",
+        allowOperationReplay,
+        ...(expectedPlacementInstanceId &&
+        (expectedPlacement?.kind === "sandbox_group" ||
+          expectedPlacement?.kind === "external_provider")
+          ? { retainedInstanceId: expectedPlacementInstanceId }
+          : {}),
       },
       async (handle) => {
         if (expectedPlacement?.kind === "sandbox_group") {
@@ -2681,8 +2957,16 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             resolved.kind !== "selfhosted" ||
             resolved.sandboxId !== expectedPlacement.sandboxId
           ) {
-            throw new BrowserSessionStateError(
-              "BrowserSession Connected Machine is not the active placement",
+            if (operation === "browser.create") {
+              throw new HTTPException(422, {
+                message:
+                  "The requested Connected Machine is not this session's current placement. Move the session to that machine before creating an interaction resource.",
+              });
+            }
+            return await throwBrowserSourcePlacementChanged(
+              grant,
+              sourceSession.id,
+              expectedPlacement.sandboxId,
             );
           }
           const placementInstanceId = resolved.providerInstanceId ?? expectedPlacement.sandboxId;
@@ -2779,7 +3063,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       !lease ||
       (lease.liveness !== "warm" && lease.liveness !== "draining") ||
       lease.instanceId !== binding.placementInstanceId ||
-      !lease.controllerDataPlaneUrl
+      !lease.controllerDataPlaneUrl ||
+      (lease.backend === "opensandbox" && deps.settings.openSandboxSignedEndpoints) ||
+      !controllerCachedUrlIsUsable(lease.controllerDataPlaneUrl)
     ) {
       return null;
     }
@@ -2805,8 +3091,29 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     if (!sandboxGroupId || !placement.lease?.instanceId || !placement.session.resolveExposedPort) {
       return placement;
     }
+    if (placement.lease.backend === "opensandbox" && deps.settings.openSandboxSignedEndpoints) {
+      if (!placement.lease.controllerDataPlaneUrl) return placement;
+      const lease = await recordLeaseControllerDataPlaneUrl(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sandboxGroupId,
+        expectedEpoch: placement.lease.leaseEpoch,
+        expectedInstanceId: placement.lease.instanceId,
+        controllerDataPlaneUrl: null,
+      });
+      return lease ? { ...placement, lease } : placement;
+    }
     const endpoint = await placement.session.resolveExposedPort(BROWSER_CONTROL_PORT);
     const url = buildStreamUrl(endpoint);
+    if (
+      !shouldPersistControllerDataPlaneUrl({
+        backend: placement.lease.backend,
+        signedEndpoints: deps.settings.openSandboxSignedEndpoints,
+        url,
+      })
+    ) {
+      return placement;
+    }
     const lease = await recordLeaseControllerDataPlaneUrl(deps.db, {
       accountId: grant.accountId,
       workspaceId,
@@ -2816,6 +3123,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       controllerDataPlaneUrl: url,
     });
     if (!lease) return placement;
+    if (!controllerCacheAllowsHostFetch(url)) {
+      return { ...placement, lease };
+    }
     return { ...placement, session: controllerOnlySession(url), lease };
   }
 
@@ -2831,7 +3141,16 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     const sandboxGroupId = placement.controllerHostSandboxGroupId;
     const cachedUrl = placement.lease?.controllerDataPlaneUrl;
     return await withCachedController({
-      cachedUrl: sandboxGroupId ? (cachedUrl ?? null) : null,
+      cachedUrl:
+        sandboxGroupId &&
+        cachedUrl &&
+        !(
+          placement.lease?.backend === "opensandbox" &&
+          routeDeps.settings.openSandboxSignedEndpoints
+        ) &&
+        controllerCachedUrlIsUsable(cachedUrl)
+          ? cachedUrl
+          : null,
       createCachedClient: (url) =>
         new BrowserControlClient(controllerOnlySession(url), { adminToken }),
       prepareCachedClient: async (client) => {
@@ -2889,6 +3208,17 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         record.sourceSessionId,
         authorizationOperation,
       );
+      let sourceSession: Session | null = null;
+      if (record.session.placement?.kind === "connected_machine") {
+        sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
+        if (sourceSession.activeSandboxId !== record.session.placement.sandboxId) {
+          return await throwBrowserSourcePlacementChanged(
+            grant,
+            record.sourceSessionId,
+            record.session.placement.sandboxId,
+          );
+        }
+      }
       if (record.session.lifecycle !== "active" || !record.session.controller) {
         throw new BrowserSessionStateError("BrowserSession is not active");
       }
@@ -2902,10 +3232,18 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       if (!admitted) {
         throw new BrowserSessionStateError("BrowserSession controller authority changed");
       }
-      const run = async (placement: BrowserPlacement): Promise<T> => {
+      const safelyReplayable =
+        browserSessionStorageMode(record.session) !== "ephemeral_context" &&
+        (channelOperation === "browser.read" || channelOperation === "browser.action");
+      let controllerTransportFailed = false;
+      const controllerRecoveryState = { attempted: false };
+      const run = async (
+        placement: BrowserPlacement,
+        provisionedClient?: BrowserControlClient,
+      ): Promise<T> => {
         // An active binding already proves browserd was provisioned. Reusing
         // it avoids restarting/checking the sidecar on every live input.
-        const client = connectController(deps, grant, record, placement);
+        const client = provisionedClient ?? connectController(deps, grant, record, placement);
         const tokens = deriveBrowserSessionControllerTokens({
           rootSecret: browserAuthorityRoot(deps),
           accountId: grant.accountId,
@@ -2934,6 +3272,30 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         try {
           result = await callback(controller);
         } catch (error) {
+          if (
+            browserSessionStorageMode(record.session) === "ephemeral_context" &&
+            (isMissingBrowserControllerSession(error) ||
+              (error instanceof BrowserControlRequestError &&
+                error.error.code === "controller_lost"))
+          ) {
+            const retired = await markEphemeralBrowserSessionLost(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+            });
+            if (retired)
+              await releaseInteractionHolder(
+                deps,
+                grant,
+                workspaceId,
+                browserSessionId,
+                record.controllerHostSandboxGroupId,
+              );
+            throw new BrowserSessionStateError(
+              "Ephemeral browser context was lost; create a new BrowserSession. No identity or operation was replayed.",
+            );
+          }
           if (!recoverMissing || !isMissingBrowserControllerSession(error)) throw error;
           await recoverActiveBrowserController(
             deps,
@@ -2943,6 +3305,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             placement,
             client,
             tokens,
+            authorizationOperation,
           );
           result = await callback(controller);
         }
@@ -2953,15 +3316,10 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         try {
           return await run(cached);
         } catch (error) {
-          const safelyReplayable =
-            channelOperation === "browser.read" || channelOperation === "browser.action";
-          if (
-            !safelyReplayable ||
-            (!(error instanceof BrowserControlTransportError) &&
-              !(error instanceof BrowserControlRequestError && error.retryable))
-          ) {
+          if (!safelyReplayable || !isRetryableControllerTransport(error)) {
             throw error;
           }
+          controllerTransportFailed = true;
           await recordLeaseControllerDataPlaneUrl(deps.db, {
             accountId: grant.accountId,
             workspaceId,
@@ -2973,7 +3331,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         }
       }
 
-      const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
+      sourceSession ??= await requireSourceSession(deps, workspaceId, record.sourceSessionId);
       return await withBrowserPlacement(
         sourceSession,
         grant,
@@ -2981,18 +3339,75 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         binding.placementInstanceId,
         channelOperation,
         context.req.raw.signal,
-        async (placement) =>
-          await run(
-            await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
-              () => placement,
-            ),
-          ),
+        async (placement) => {
+          const use = async () =>
+            await run(
+              await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
+                () => placement,
+              ),
+            );
+          if (browserSessionStorageMode(record.session) === "ephemeral_context") return await use();
+          return await withControllerTransportRecovery({
+            channelOperation,
+            placementKind: placement.placement.kind,
+            recoveryState: controllerRecoveryState,
+            transportAlreadyFailed: controllerTransportFailed,
+            use,
+            admitRecovery: async () => {
+              if (
+                !(await touchBrowserSessionController(deps.db, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  browserSessionId,
+                  controllerGeneration: binding.controllerGeneration,
+                }))
+              ) {
+                throw new BrowserSessionStateError("BrowserSession controller authority changed");
+              }
+            },
+            recover: async () => {
+              // Provision and restore through the original exec-capable session;
+              // the cached tunnel alone cannot start browserd or its display.
+              const client = await provisionController(
+                deps,
+                grant,
+                record,
+                placement,
+                requestOrigin(context, deps.settings),
+              );
+              await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
+                () => placement,
+              );
+              return await run(placement, client);
+            },
+          });
+        },
+        browserSessionStorageMode(record.session) !== "ephemeral_context",
       );
     } catch (error) {
       throw browserRouteError(error);
     }
   }
 
+  async function throwBrowserSourcePlacementChanged(
+    grant: AccessGrant,
+    sourceSessionId: string,
+    connectedSandboxId: string,
+  ): Promise<never> {
+    const reconciliation = await terminalizeStaleConnectedInteractionPlacement(deps.db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      sourceSessionId,
+      connectedSandboxId,
+    });
+    if (reconciliation.sourcePlacementChanged) {
+      throw sourcePlacementChangedApiError("browser_session");
+    }
+    throw new BrowserSessionStateError(
+      "BrowserSession source placement changed during the request; retry",
+    );
+  }
+
   async function recoverActiveBrowserController(
     routeDeps: ApiRouteDeps,
     grant: AccessGrant,
@@ -3001,12 +3416,72 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     placement: BrowserPlacement,
     client: BrowserControlClient,
     tokens: ReturnType<typeof deriveBrowserSessionControllerTokens>,
+    authorizationOperation: SessionAuthorizationOperation,
   ): Promise<void> {
-    const linkedComputer = await requireLinkedComputerBinding(
+    if (browserSessionStorageMode(record.session) === "ephemeral_context") {
+      throw new BrowserSessionStateError(
+        "Ephemeral browser context was lost; create a new BrowserSession. Its identity and operations cannot be restored or replayed.",
+      );
+    }
+    const transport = browserRuntimeTransport(record.session, placement.transport);
+    const recoverWorkingDirectory =
+      transport.kind === "managed" &&
+      transport.engine === "chromium" &&
+      !transport.ephemeralPartition &&
+      browserSessionStorageMode(record.session) === "private_profile";
+    if (recoverWorkingDirectory) {
+      // Missing controller memory cannot admit a stale source, token, placement
+      // or route snapshot. Reuse the existing durable authority before recovery.
+      await authorizeSourceSession(
+        routeDeps,
+        grant,
+        record.sourceSessionId,
+        authorizationOperation,
+      );
+      const current = await getBrowserSessionControlRecord(routeDeps.db, {
+        accountId: grant.accountId,
+        workspaceId: record.session.workspaceId,
+        browserSessionId: record.session.id,
+      });
+      if (
+        current.sourceSessionId !== record.sourceSessionId ||
+        current.session.lifecycle !== "active" ||
+        current.session.controller?.controllerGeneration !== binding.controllerGeneration ||
+        current.session.controller.placementInstanceId !== placement.placementInstanceId ||
+        current.session.controller.controllerId !== binding.controllerId ||
+        current.tokenGeneration !== record.tokenGeneration ||
+        !sameInteractionPlacement(current.session.placement, record.session.placement) ||
+        current.session.driverId !== record.session.driverId ||
+        current.session.engine !== record.session.engine ||
+        current.session.headless !== record.session.headless ||
+        current.session.linkedComputerSessionId !== record.session.linkedComputerSessionId ||
+        current.session.networkRouteId !== record.session.networkRouteId ||
+        JSON.stringify(current.networkRouteAuthority) !==
+          JSON.stringify(record.networkRouteAuthority)
+      ) {
+        throw new BrowserSessionStateError("BrowserSession controller authority changed");
+      }
+      if (record.session.placement.kind === "connected_machine") {
+        const source = await requireSourceSession(
+          routeDeps,
+          record.session.workspaceId,
+          record.sourceSessionId,
+        );
+        if (source.activeSandboxId !== record.session.placement.sandboxId) {
+          return await throwBrowserSourcePlacementChanged(
+            grant,
+            record.sourceSessionId,
+            record.session.placement.sandboxId,
+          );
+        }
+      }
+    }
+    const linkedComputer = await ensureLinkedComputerController(
       routeDeps,
       grant,
       record.session,
       placement,
+      client,
     );
     const networkRoute = await resolveActiveBrowserNetworkRouteLaunch({
       deps: routeDeps,
@@ -3015,13 +3490,30 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       placement: placement.placement,
     });
     try {
+      await ensureHeadedBrowserDisplayStack(
+        placement.session,
+        record.session.headless,
+        linkedComputer !== null,
+      );
+      if (
+        recoverWorkingDirectory &&
+        !(await touchBrowserSessionController(routeDeps.db, {
+          accountId: grant.accountId,
+          workspaceId: record.session.workspaceId,
+          browserSessionId: record.session.id,
+          controllerGeneration: binding.controllerGeneration,
+        }))
+      ) {
+        throw new BrowserSessionStateError("BrowserSession controller authority changed");
+      }
       await client.createSession({
         browserSessionId: record.session.id,
         controllerGeneration: binding.controllerGeneration,
         tokenGeneration: record.tokenGeneration,
         ...tokens,
         headed: !record.session.headless,
-        transport: browserRuntimeTransport(record.session, placement.transport),
+        transport,
+        ...(recoverWorkingDirectory ? { recoverExistingWorkingDirectory: true } : {}),
         ...(linkedComputer ? { linkedComputer } : {}),
         ...(networkRoute ? { networkRoute } : {}),
       });
@@ -3065,7 +3557,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             grant,
             record,
             placement,
-            requestOrigin(context, deps.settings.corsAllowOriginRegex),
+            requestOrigin(context, deps.settings),
           );
           await endCapturedBrowserController(client, browserSessionId, binding);
           await clearSuspendedBrowserSessionController(deps.db, {
@@ -3087,18 +3579,42 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
   }
 }
 
-function browserCreateInput(
+function sourcePlacementChangedApiError(interactionResource: "browser_session"): ApiHttpError {
+  return new ApiHttpError(409, {
+    code: "conflict",
+    message:
+      "This browser belonged to a previous task placement and was retired. Open a new browser.",
+    retryable: false,
+    outcomeUnknown: false,
+    details: {
+      interactionResource,
+      interactionFailureCode: "source_placement_changed",
+      interactionLifecycle: "lost",
+    },
+  });
+}
+
+export function browserCreateInput(
   grant: AccessGrant,
   workspaceId: string,
   request: CreateBrowserSessionRequestValue,
   placement: InteractionPlacement,
 ) {
+  if (request.storageMode === "ephemeral_context" && placement.kind !== "sandbox_group") {
+    throw new BrowserControlUnsupportedError(
+      "Ephemeral contexts require a managed sandbox placement",
+    );
+  }
   const attached = placement.kind === "attached_device";
   const external = placement.kind === "external_provider";
   const engine = attached ? ("chrome" as const) : external ? ("external" as const) : request.engine;
-  if (engine === "lightpanda" && placement.kind !== "sandbox_group") {
+  if (
+    request.engine === "lightpanda" &&
+    placement.kind !== "sandbox_group" &&
+    placement.kind !== "connected_machine"
+  ) {
     throw new BrowserControlUnsupportedError(
-      "Lightpanda is currently available only in managed agent sandboxes",
+      "Lightpanda requires a managed sandbox or Connected Machine browser placement",
     );
   }
   return {
@@ -3111,11 +3627,13 @@ function browserCreateInput(
     initialUrl: request.initialUrl ?? null,
     placement,
     driverId:
-      engine === "lightpanda"
-        ? LIGHTPANDA_DRIVER_ID
-        : external
-          ? EXTERNAL_BROWSER_DRIVER_ID
-          : BROWSER_DRIVER_ID,
+      request.storageMode === "ephemeral_context"
+        ? EPHEMERAL_CHROMIUM_DRIVER_ID
+        : engine === "lightpanda"
+          ? LIGHTPANDA_DRIVER_ID
+          : external
+            ? EXTERNAL_BROWSER_DRIVER_ID
+            : BROWSER_DRIVER_ID,
     engine,
     headless: attached ? false : request.headless,
     identityId: request.identityId ?? null,
@@ -3140,7 +3658,21 @@ function browserCreateInput(
 function browserRuntimeTransport(
   session: BrowserSessionValue,
   transport: PlacementBrowserTransport,
+  placementInstanceId?: string,
+  rootSecret?: string,
 ): PlacementBrowserTransport {
+  if (browserSessionStorageMode(session) === "ephemeral_context") {
+    if (transport.kind !== "managed" || !placementInstanceId || !rootSecret) {
+      throw new BrowserControlUnsupportedError(
+        "Ephemeral contexts cannot recover or change their placement",
+      );
+    }
+    return {
+      kind: "managed",
+      engine: "chromium",
+      ephemeralPartition: ephemeralBrowserPartition(session, placementInstanceId, rootSecret),
+    };
+  }
   if (transport.kind !== "managed") return transport;
   return {
     kind: "managed",
@@ -3202,6 +3734,11 @@ function assertCreateReplay(
       "BrowserSession create operation is bound to another placement",
     );
   }
+  if (request.storageMode !== browserSessionStorageMode(session)) {
+    throw new BrowserSessionOperationConflictError(
+      "BrowserSession create operation is bound to another storage mode",
+    );
+  }
   const expectedEngine =
     session.placement.kind === "attached_device"
       ? "chrome"
@@ -3235,11 +3772,39 @@ function assertCreateReplay(
   }
 }
 
-async function requireLinkedComputerBinding(
+async function ensureHeadedBrowserDisplayStack(
+  session: BrowserControlPlacementSession,
+  headless: boolean,
+  linkedComputer: boolean,
+): Promise<void> {
+  if (
+    !browserNeedsStandaloneDisplayStack({
+      headless,
+      linkedComputer,
+      nativeBrowserControl: typeof session.ensureBrowserControl === "function",
+    })
+  )
+    return;
+  if (typeof session.exec !== "function" && typeof session.execCommand !== "function") return;
+  await ensureDisplayStack(session, {
+    telemetryContext: { callerKind: "viewer" },
+  });
+}
+
+export function browserNeedsStandaloneDisplayStack(input: {
+  headless: boolean;
+  linkedComputer: boolean;
+  nativeBrowserControl: boolean;
+}): boolean {
+  return !input.headless && !input.linkedComputer && !input.nativeBrowserControl;
+}
+
+async function ensureLinkedComputerController(
   deps: ApiRouteDeps,
   grant: AccessGrant,
   browser: BrowserSessionValue,
   placement: BrowserPlacement,
+  client: BrowserControlClient,
 ): Promise<{ computerSessionId: string; controllerGeneration: string } | null> {
   if (!browser.linkedComputerSessionId) return null;
   const record = await getComputerSessionControlRecord(deps.db, {
@@ -3257,10 +3822,42 @@ async function requireLinkedComputerBinding(
       "Linked ComputerSession is not active on the browser placement",
     );
   }
-  return {
+  const reference = {
     computerSessionId: record.session.id,
     controllerGeneration: record.session.controller.controllerGeneration,
   };
+  const tokens = deriveComputerSessionControllerTokens({
+    rootSecret: browserAuthorityRoot(deps),
+    accountId: grant.accountId,
+    workspaceId: browser.workspaceId,
+    placement: record.session.placement,
+    placementInstanceId: placement.placementInstanceId,
+    computerSessionId: record.session.id,
+    controllerGeneration: record.session.controller.controllerGeneration,
+    tokenGeneration: record.tokenGeneration,
+  });
+  const sessionClient = client.computerSessionClient({ reference, ...tokens });
+  try {
+    await sessionClient.heartbeat();
+  } catch (error) {
+    if (!isMissingLinkedComputerControllerSession(error)) throw error;
+    await client.createComputerSession({
+      ...reference,
+      tokenGeneration: record.tokenGeneration,
+      ...tokens,
+    });
+  }
+  return reference;
+}
+
+function isMissingLinkedComputerControllerSession(error: unknown): boolean {
+  if (!(error instanceof BrowserControlRequestError)) return false;
+  if (error.status === 401 && error.error.code === "permission_denied") return true;
+  return (
+    error.status === 404 &&
+    error.error.code === "resource_not_found" &&
+    ["computer session not found", "computer session is not active"].includes(error.error.message)
+  );
 }
 
 async function requireBrowserRevisionRestoreAuthority(
@@ -3480,6 +4077,7 @@ async function ensureInteractionHolder(
   if (!placement.lease?.instanceId) {
     throw new BrowserSessionStateError("BrowserSession lease placement is unavailable");
   }
+  const sandboxRuntime = await resolveSessionSandboxRuntime(deps.db, deps.settings, sourceSession);
   const acquired = await acquireLease(deps.db, {
     accountId: grant.accountId,
     workspaceId: sourceSession.workspaceId,
@@ -3488,9 +4086,14 @@ async function ensureInteractionHolder(
     holderId: interactionHolderId(browserSessionId),
     subjectId: sourceSession.id,
     backend: placement.lease.backend,
+    warmBilling: {
+      mode: deps.settings.sandboxWarmBillingMode,
+      rateMicrosPerSecond: sandboxWarmRateMicrosPerSecond(deps.settings, placement.lease.backend),
+    },
     os: placement.lease.os,
-    image: placement.lease.image,
-    rigVersionId: placement.lease.rigVersionId,
+    image: sandboxRuntime.image,
+    imagePolicy: "new_creates_only",
+    rigVersionId: sourceSession.rigVersionId,
     leaseTtlMs: deps.settings.sandboxLeaseTtlMs,
     expectedEpoch: placement.lease.leaseEpoch,
     waitSignal,
@@ -3512,6 +4115,11 @@ async function ensureInteractionHolder(
     ).catch(() => undefined);
     throw new BrowserSessionStateError("BrowserSession placement fence changed; retry");
   }
+  await renewSandboxProviderExpiration({
+    backend: acquired.lease.backend as ApiRouteDeps["settings"]["sandboxBackend"],
+    settings: deps.settings,
+    instanceId: acquired.lease.instanceId,
+  }).catch(() => false);
   return true;
 }
 
@@ -3758,6 +4366,7 @@ async function settleBrowserSessionSuspensionCaptureFailure(
   return await failBrowserSessionSuspension(deps.db, {
     ...input,
     ...(outcomeUnknown ? { state: "outcome_unknown" as const } : {}),
+    missingControllerSession: error.status === 404 && isMissingBrowserControllerSession(error),
     error: error.error,
   });
 }
@@ -3895,6 +4504,66 @@ function optionalBoundedInteger(
   return parsed;
 }
 
+export function parseBrowserScreenshotOptions(
+  query: URLSearchParams,
+): BrowserControlScreenshotOptions {
+  for (const key of ["fullPage", "format", "quality"]) {
+    if (query.getAll(key).length > 1) {
+      throw new HTTPException(400, { message: `duplicate browser screenshot ${key}` });
+    }
+  }
+  const fullPage = query.get("fullPage");
+  if (fullPage !== null && fullPage !== "true" && fullPage !== "false") {
+    throw new HTTPException(400, { message: "invalid browser screenshot fullPage" });
+  }
+  const format = query.get("format");
+  if (format !== null && format !== "jpeg" && format !== "png") {
+    throw new HTTPException(400, { message: "invalid browser screenshot format" });
+  }
+  const quality = query.get("quality");
+  const parsedQuality = quality === null ? null : optionalBoundedInteger(quality, 1, 100);
+  if (quality !== null && parsedQuality === null) {
+    throw new HTTPException(400, { message: "invalid browser screenshot quality" });
+  }
+  return {
+    ...(fullPage === null ? {} : { fullPage: fullPage === "true" }),
+    ...(format === null ? {} : { format }),
+    ...(parsedQuality === null ? {} : { quality: parsedQuality }),
+  };
+}
+
+/** Keep a definite read timeout useful without publishing driver diagnostics. */
+export function browserScreenshotError(error: unknown): unknown {
+  if (error instanceof BrowserControlRequestError && error.error.code === "timeout") {
+    const failure = new ApiHttpError(504, {
+      code: "upstream_unavailable",
+      message:
+        "This tab did not produce a screenshot in time. Other browser operations may still work.",
+      retryable: error.retryable,
+      outcomeUnknown: false,
+    });
+    failure.cause = error;
+    return failure;
+  }
+  return error;
+}
+
+export function browserScreenshotResponse(
+  frame: Pick<BrowserControlFrame, "data" | "mediaType" | "metadataHeader">,
+): Response {
+  // Node Buffers can be views into a larger backing allocation. Copy exactly
+  // the image bytes before constructing the Response.
+  return new Response(Uint8Array.from(frame.data).buffer, {
+    status: 200,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": frame.mediaType,
+      "x-opengeni-browser-frame": frame.metadataHeader,
+      ...USER_CONTENT_SECURITY_HEADERS,
+    },
+  });
+}
+
 function isUuid(value: unknown): value is string {
   return (
     typeof value === "string" &&
@@ -3902,32 +4571,8 @@ function isUuid(value: unknown): value is string {
   );
 }
 
-function requestOrigin(context: Context, allowedPattern: string): string | null {
-  return validateBrowserRequestOrigin(context.req.header("origin"), allowedPattern);
-}
-
-export function validateBrowserRequestOrigin(
-  value: string | undefined,
-  allowedPattern: string,
-): string | null {
-  if (!value) return null;
-  let url: URL;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new HTTPException(400, { message: "invalid request origin" });
-  }
-  if (
-    url.origin === "null" ||
-    (url.protocol !== "http:" && url.protocol !== "https:") ||
-    url.origin !== value
-  ) {
-    throw new HTTPException(400, { message: "invalid request origin" });
-  }
-  if (!allowedCorsOrigin(allowedPattern, url.origin)) {
-    throw new HTTPException(403, { message: "request origin is not allowed" });
-  }
-  return url.origin;
+function requestOrigin(context: Context, settings: ApiRouteDeps["settings"]): string | null {
+  return validateInteractionRequestOrigin(context.req.header("origin"), settings);
 }
 
 export function interactionActorForGrant(
@@ -3955,6 +4600,20 @@ function assertPlacementInstance(expected: string | null, actual: string): void
   }
 }
 
+/** End keeps the original controller token fence so a later Chrome generation
+ *  can still dispose the stale browserd session. */
+function attachedEndPlacementInstanceId(
+  operation: ChannelAOperation,
+  expectedPlacementInstanceId: string | null,
+  liveGeneration: string,
+): string {
+  if (operation === "browser.end" && expectedPlacementInstanceId) {
+    return expectedPlacementInstanceId;
+  }
+  assertPlacementInstance(expectedPlacementInstanceId, liveGeneration);
+  return liveGeneration;
+}
+
 function isTerminalOperation(state: string): boolean {
   return state === "completed" || state === "failed" || state === "outcome_unknown";
 }
@@ -4410,9 +5069,14 @@ async function finalizeBrowserDownloadFile(
   if (upload.expiresAt.getTime() <= Date.now()) {
     throw new InteractionResourceStateError("Browser download file upload authority expired");
   }
-  const head = await objectStorage.headFile(upload.file).catch(() => {
-    throw new HTTPException(503, { message: "browser download object is not available" });
+  const pendingFile = upload.file;
+  const head = await retryWhileMissing(async () => {
+    if (!(await objectStorage.fileExists(pendingFile))) return null;
+    return await objectStorage.headFile(pendingFile);
   });
+  if (!head) {
+    throw new HTTPException(503, { message: "browser download object is not available" });
+  }
   if (
     Number(head.ContentLength ?? -1) !== upload.file.sizeBytes ||
     (head.ContentType !== undefined && head.ContentType !== upload.file.contentType) ||
@@ -4453,7 +5117,11 @@ async function recordBrowserDownloadFileUsage(
 }
 
 function browserRouteError(error: unknown): HTTPException {
+  const connectedMachineError = interactionControlApiError(error, "browser");
+  if (connectedMachineError) return connectedMachineError;
   if (error instanceof HTTPException) return error;
+  if (error instanceof SandboxPaidComputeAdmissionError)
+    return new HTTPException(402, { message: error.message, cause: error });
   if (error instanceof BrowserSessionNotFoundError) {
     return new HTTPException(404, { message: error.message, cause: error });
   }