@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/routes/browser-sessions.ts

@@ -59,6 +59,7 @@ import {
   type SiteAuthAuthority,
 } from "@opengeni/contracts";
 import {
+  getSessionAuthorityEpoch,
   acquireLease,
   activateBrowserSession,
   ATTACHED_BROWSER_SESSION_CAPABILITIES,
@@ -95,10 +96,11 @@ import {
   findBrowserDownloadSave,
   getBrowserSessionControlRecord,
   getComputerSessionControlRecord,
+  getBrowserIdentity,
   getBrowserPrivateCheckpointAuthority,
   getAttachedBrowserDevice,
   getBrowserRevisionArtifactAuthority,
-  getEnrollment,
+  getLiveEnrollmentConnection,
   getExternalAuthInteractiveContext,
   getFilesForSubject,
   getFileUpload,
@@ -131,6 +133,7 @@ import {
   touchBrowserSessionController,
   verifyAuthRun,
   settleBrowserDownloadSaveFailure,
+  terminalizeStaleConnectedInteractionPlacement,
   type BrowserSessionControlRecord,
   type BrowserPrivateCheckpointAuthority,
   type BrowserRevisionArtifactAuthority,
@@ -142,6 +145,7 @@ import {
   recordWorkspaceUsage,
   requireLimit,
   relayConfigFromSettings,
+  resolveSessionSandboxRuntime,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   type ApiRouteDeps,
@@ -158,16 +162,19 @@ import {
   buildStreamUrl,
   exposedPortEndpointFromUrl,
   buildSelfhostedBackendSession,
+  ensureDisplayStack,
   mintStreamToken,
   NatsControlRpc,
   NatsOpStreamTransport,
   provisionBrowserControlClient,
+  renewSandboxProviderExpiration,
   type BrowserControlPlacementSession,
   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 +183,14 @@ import {
   deriveBrowserNetworkRouteAuthorityDigest,
   deriveBrowserSessionControllerTokens,
   deriveBrowserViewGrantToken,
+  deriveComputerSessionControllerTokens,
 } from "../browser-controller-authority";
-import { withCachedController } from "../controller-data-plane";
+import {
+  controllerCacheAllowsHostFetch,
+  controllerCachedUrlIsUsable,
+  shouldPersistControllerDataPlaneUrl,
+  withCachedController,
+} from "../controller-data-plane";
 import { withInteractionHolderHeartbeat } from "../interaction-holder-heartbeat";
 import {
   browserStateArtifactAad,
@@ -192,7 +205,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,
@@ -298,7 +317,7 @@ 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);
 
     try {
@@ -325,6 +344,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 +434,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 +459,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,8 +478,13 @@ 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,
@@ -456,8 +495,10 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                         ...(networkRoute ? { networkRoute } : {}),
                         ...(request.initialUrl ? { initialUrl: request.initialUrl } : {}),
                         ...(restore ? { restore } : {}),
-                      }),
-                  ),
+                      });
+                    },
+                  );
+                },
               );
               await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
                 () => placement,
@@ -1663,7 +1704,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,
@@ -1719,6 +1760,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 +1779,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,14 +1795,44 @@ 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,
@@ -1958,7 +2043,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);
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2184,7 +2269,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 +2388,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 +2411,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 +2429,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 +2445,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                     ...(linkedComputer ? { linkedComputer } : {}),
                     ...(networkRoute ? { networkRoute } : {}),
                     restore: restore!,
-                  }),
+                  });
+                },
               );
             } catch (error) {
               if (!isDefiniteBrowserControllerFailure(error)) throw error;
@@ -2426,7 +2518,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);
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2573,18 +2665,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 +2696,10 @@ 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,
         ...(deps.settings.agentOpStreamEnabled === true &&
         enrollment.opStream === true &&
         deps.bus.getOpStreamConnection
@@ -2609,13 +2716,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,
         },
@@ -2681,8 +2788,10 @@ 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",
+            return await throwBrowserSourcePlacementChanged(
+              grant,
+              sourceSession.id,
+              expectedPlacement.sandboxId,
             );
           }
           const placementInstanceId = resolved.providerInstanceId ?? expectedPlacement.sandboxId;
@@ -2779,7 +2888,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 +2916,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 +2948,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 +2966,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 +3033,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");
       }
@@ -2973,7 +3128,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,
@@ -2993,6 +3148,25 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     }
   }
 
+  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,
@@ -3002,11 +3176,12 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     client: BrowserControlClient,
     tokens: ReturnType<typeof deriveBrowserSessionControllerTokens>,
   ): Promise<void> {
-    const linkedComputer = await requireLinkedComputerBinding(
+    const linkedComputer = await ensureLinkedComputerController(
       routeDeps,
       grant,
       record.session,
       placement,
+      client,
     );
     const networkRoute = await resolveActiveBrowserNetworkRouteLaunch({
       deps: routeDeps,
@@ -3015,6 +3190,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       placement: placement.placement,
     });
     try {
+      await ensureHeadedBrowserDisplayStack(
+        placement.session,
+        record.session.headless,
+        linkedComputer !== null,
+      );
       await client.createSession({
         browserSessionId: record.session.id,
         controllerGeneration: binding.controllerGeneration,
@@ -3065,7 +3245,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,6 +3267,21 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
   }
 }
 
+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",
+    },
+  });
+}
+
 function browserCreateInput(
   grant: AccessGrant,
   workspaceId: string,
@@ -3235,11 +3430,31 @@ function assertCreateReplay(
   }
 }
 
-async function requireLinkedComputerBinding(
+async function ensureHeadedBrowserDisplayStack(
+  session: BrowserControlPlacementSession,
+  headless: boolean,
+  linkedComputer: boolean,
+): Promise<void> {
+  if (!browserNeedsStandaloneDisplayStack({ headless, linkedComputer })) 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;
+}): boolean {
+  return !input.headless && !input.linkedComputer;
+}
+
+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 +3472,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 +3727,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,
@@ -3489,8 +3737,8 @@ async function ensureInteractionHolder(
     subjectId: sourceSession.id,
     backend: placement.lease.backend,
     os: placement.lease.os,
-    image: placement.lease.image,
-    rigVersionId: placement.lease.rigVersionId,
+    image: sandboxRuntime.image,
+    rigVersionId: sourceSession.rigVersionId,
     leaseTtlMs: deps.settings.sandboxLeaseTtlMs,
     expectedEpoch: placement.lease.leaseEpoch,
     waitSignal,
@@ -3512,6 +3760,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;
 }
 
@@ -3902,32 +4155,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 +4184,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 +4653,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,6 +4701,8 @@ 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 BrowserSessionNotFoundError) {
     return new HTTPException(404, { message: error.message, cause: error });