@opengeni/api-router 0.26.1 → 0.30.0

package/src/routes/browser-sessions.ts

@@ -7,6 +7,7 @@ import {
 import {
   BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX,
   BROWSER_CONTROL_WEBSOCKET_PROTOCOL,
+  BROWSER_CONTROL_PORT,
   BROWSER_CONTROL_PROTOCOL_VERSION,
   BROWSER_PROFILE_ARTIFACT_FORMAT,
   BROWSER_STATE_ARTIFACT_CONTENT_TYPE,
@@ -15,7 +16,14 @@ import {
   BrowserActionCommand,
   BrowserActionRequest,
   BrowserDiagnosticKind,
+  BrowserDownload,
+  BrowserDownloadSaveRequest,
+  BrowserDownloadSaveResponse,
+  BrowserDownloadListResponse,
+  BrowserExternalAuthCommand,
   BrowserOpenTargetRequest,
+  BrowserObservation,
+  BrowserProtectedAuthFillCommand,
   BrowserSessionAttachment,
   BrowserSessionAttachmentRequest,
   BrowserSessionHeartbeatResponse,
@@ -24,56 +32,105 @@ import {
   BrowserSessionMutationResponse,
   BrowserTargetListResponse,
   CreateBrowserSessionRequest,
+  ExternalAuthInteractiveRequest,
+  ExternalAuthInteractiveResponse,
+  ExternalAuthRunRequest,
+  ExternalAuthRunResponse,
   InteractionActor,
+  ProtectedAuthFillRequest,
+  ProtectedAuthFillResponse,
+  ReportAuthRunRequest,
+  StartAuthRunRequest,
+  VerifyAuthRunRequest,
   PublishBrowserRevisionRequest,
   PublishBrowserRevisionResponse,
   type AccessGrant,
+  type BrowserProtectedAuthFillReceipt as BrowserProtectedAuthFillReceiptValue,
+  type BrowserActionRequest as BrowserActionRequestValue,
+  type BrowserDownload as BrowserDownloadValue,
   type BrowserSession as BrowserSessionValue,
+  type FileAsset,
   type CreateBrowserSessionRequest as CreateBrowserSessionRequestValue,
   type InteractionPlacement,
+  type InteractionCredentialAuthorityRef,
   type BrowserRevisionMaterialization as BrowserRevisionMaterializationValue,
   type Session,
   type SessionAuthorizationOperation,
+  type SiteAuthAuthority,
 } from "@opengeni/contracts";
 import {
   acquireLease,
   activateBrowserSession,
   ATTACHED_BROWSER_SESSION_CAPABILITIES,
+  EXTERNAL_BROWSER_SESSION_CAPABILITIES,
+  LIGHTPANDA_BROWSER_SESSION_CAPABILITIES,
+  bindBrowserSessionNetworkRouteAuthority,
   AttachedBrowserDeviceNotFoundError,
   BrowserIdentityConflictError,
   BrowserIdentityNotFoundError,
   BrowserIdentityStateError,
+  BrowserStateUploadStateError,
   clearSuspendedBrowserSessionController,
   BrowserSessionNotFoundError,
   BrowserSessionOperationConflictError,
   BrowserSessionStateError,
   completeBrowserSessionEnd,
+  completeExternalAuth,
+  completeBrowserDownloadSave,
+  completeFileUpload,
+  completeProtectedAuthFill,
   commitBrowserSessionSuspension,
   commitBrowserRevisionPublication,
   dispatchBrowserRevisionPublication,
+  dispatchBrowserDownloadSave,
   dispatchBrowserSessionOperation,
+  dispatchExternalAuth,
+  dispatchProtectedAuthFill,
   failBrowserSessionOperation,
   failBrowserSessionResume,
   failBrowserSessionResumePreparation,
   failBrowserSessionSuspension,
   failBrowserRevisionPublication,
   findBrowserSessionControlRecordByOperation,
+  findBrowserDownloadSave,
   getBrowserSessionControlRecord,
   getComputerSessionControlRecord,
   getBrowserPrivateCheckpointAuthority,
   getAttachedBrowserDevice,
   getBrowserRevisionArtifactAuthority,
   getEnrollment,
+  getExternalAuthInteractiveContext,
+  getFiles,
+  getFileUpload,
+  getAuthRun,
+  getExternalAuthPreparation,
+  getProtectedAuthFillPreparation,
+  getSiteAuthConnection,
   getSession,
+  InteractionResourceConflictError,
+  InteractionResourceNotFoundError,
+  InteractionResourceStateError,
+  listAuthRuns,
   listBrowserSessions,
   listAttachedBrowserDevices,
   prepareBrowserSessionCreate,
+  prepareExternalAuth,
+  prepareBrowserDownloadSave,
   prepareBrowserSessionEnd,
   prepareBrowserSessionResume,
   prepareBrowserSessionSuspend,
   prepareBrowserRevisionPublication,
+  prepareProtectedAuthFill,
+  reportAuthRun,
   releaseLeaseHolder,
+  readLease,
+  recordLeaseControllerDataPlaneUrl,
+  loadConnectionCredentialForBroker,
+  markProtectedAuthFillOutcomeUnknown,
+  startAuthRun,
   touchBrowserSessionController,
+  verifyAuthRun,
+  settleBrowserDownloadSaveFailure,
   type BrowserSessionControlRecord,
   type BrowserPrivateCheckpointAuthority,
   type BrowserRevisionArtifactAuthority,
@@ -82,6 +139,8 @@ import {
 import {
   requireAccessGrant,
   requireSessionAuthorization,
+  recordWorkspaceUsage,
+  requireLimit,
   relayConfigFromSettings,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
@@ -89,20 +148,22 @@ import {
 } from "@opengeni/core";
 import {
   BrowserControlProtocolError,
+  BrowserControlClient,
   BrowserControlRequestError,
   BrowserControlServerError,
   BrowserControlServerUnsupportedError,
   BrowserControlTransportError,
   BrowserControlUnsupportedError,
   buildStreamUrl,
+  exposedPortEndpointFromUrl,
   buildSelfhostedBackendSession,
   mintStreamToken,
   NatsControlRpc,
   NatsOpStreamTransport,
   provisionBrowserControlClient,
-  type BrowserControlClient,
   type BrowserControlPlacementSession,
   type PlacementBrowserStateCaptureReceipt,
+  type PlacementBrowserNetworkRoute,
   type PlacementBrowserTransport,
   type RestorePlacementBrowserStateInput,
 } from "@opengeni/runtime/sandbox";
@@ -111,9 +172,12 @@ import { HTTPException } from "hono/http-exception";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import {
   deriveBrowserControllerAdminToken,
+  deriveBrowserNetworkRouteAuthorityDigest,
   deriveBrowserSessionControllerTokens,
   deriveBrowserViewGrantToken,
 } from "../browser-controller-authority";
+import { withCachedController } from "../controller-data-plane";
+import { withInteractionHolderHeartbeat } from "../interaction-holder-heartbeat";
 import {
   browserStateArtifactAad,
   browserStateManifestDigest,
@@ -122,13 +186,30 @@ import {
   unwrapBrowserStateDataKey,
   wrapBrowserStateDataKey,
 } from "../browser-state-authority";
+import {
+  BrowserAuthCredentialError,
+  resolveProtectedAuthFieldValues,
+} from "../browser-auth-broker";
+import { managedNetworkRouteForPlacement } from "../browser-network-route";
 import { allowedCorsOrigin } from "../http/cors";
-import { withChannelA, type ChannelAOperation } from "../sandbox/channel-a";
+import {
+  observeAuthMutation,
+  observeBrowserActionResult,
+  observeBrowserRevisionPublication,
+  observeLifecycleResult,
+} from "../interaction-metrics";
+import { withChannelA, withChannelARead, type ChannelAOperation } from "../sandbox/channel-a";
+import { sanitizeFilename } from "./files";
 
 const BROWSER_DRIVER_ID = "opengeni.cdp.v1";
+const LIGHTPANDA_DRIVER_ID = "opengeni.lightpanda.cdp.v1";
+const EXTERNAL_BROWSER_DRIVER_ID = "opengeni.external.cdp.v1";
+const BROWSER_WORKSPACE_FILE_AUTHORITY_TTL_SECONDS = 20 * 60;
+const BROWSER_STATE_UPLOAD_CLEANUP_GRACE_MS = 24 * 60 * 60 * 1_000;
 
 type BrowserPlacement = {
   placement: InteractionPlacement;
+  controllerHostSandboxGroupId: string | null;
   placementInstanceId: string;
   session: BrowserControlPlacementSession;
   lease: LeaseSnapshot | null;
@@ -214,6 +295,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     const workspaceId = context.req.param("workspaceId");
     const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
     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 authority = browserAuthorityRoot(deps);
@@ -237,7 +319,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           )
         : null;
       if (prepared && isTerminalOperation(prepared.operation.state)) {
-        return context.json(BrowserSessionMutationResponse.parse(prepared), 200);
+        const parsed = BrowserSessionMutationResponse.parse(prepared);
+        observeLifecycleResult(deps.observability, startedAtMs, parsed);
+        return context.json(parsed, 200);
       }
 
       const sourceSession = await requireSourceSession(deps, workspaceId, request.sessionId);
@@ -278,6 +362,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           );
 
           try {
+            const networkRoute = await resolveBrowserNetworkRouteLaunch({
+              deps,
+              grant,
+              workspaceId,
+              browserSessionId: prepared.session.id,
+              operationId: request.operationId,
+              rootSecret: authority,
+              placement: placement.placement,
+            });
             const interactionHeld = await ensureInteractionHolder(
               deps,
               grant,
@@ -293,7 +386,19 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               prepared.session.id,
               request.operationId,
               placement.placementInstanceId,
-            );
+            ).catch(async (error: unknown) => {
+              if (interactionHeld) {
+                await releaseInteractionHolder(
+                  deps,
+                  grant,
+                  workspaceId,
+                  prepared!.session.id,
+                  placement.controllerHostSandboxGroupId,
+                ).catch(() => undefined);
+              }
+              throw error;
+            });
+            const preparedSession = prepared.session;
             const controllerGeneration = requireOperationGeneration(record);
             const linkedComputer = await requireLinkedComputerBinding(
               deps,
@@ -319,22 +424,43 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               tokenGeneration: record.tokenGeneration,
             });
             try {
-              const { client } = await provisionBrowserControlClient(placement.session, {
+              await withBrowserCreationController(
+                deps,
+                grant,
+                workspaceId,
+                placement,
                 adminToken,
-                nativeAuthority: nativeBrowserControllerAuthority(workspaceId, placement),
-                ...(origin ? { allowedOrigins: [origin] } : {}),
-              });
-              await client.createSession({
-                browserSessionId: prepared.session.id,
-                controllerGeneration,
-                tokenGeneration: record.tokenGeneration,
-                ...tokens,
-                headed: !prepared.session.headless,
-                transport: placement.transport,
-                ...(linkedComputer ? { linkedComputer } : {}),
-                ...(request.initialUrl ? { initialUrl: request.initialUrl } : {}),
-                ...(restore ? { restore } : {}),
-              });
+                origin,
+                async (client) =>
+                  await withInteractionHolderHeartbeat(
+                    deps,
+                    {
+                      grant,
+                      workspaceId,
+                      sandboxGroupId: placement.controllerHostSandboxGroupId,
+                      holderId: interactionHolderId(preparedSession.id),
+                      operationId: request.operationId,
+                      resourceId: preparedSession.id,
+                      controllerGeneration,
+                    },
+                    async () =>
+                      await client.createSession({
+                        browserSessionId: preparedSession.id,
+                        controllerGeneration,
+                        tokenGeneration: record.tokenGeneration,
+                        ...tokens,
+                        headed: !preparedSession.headless,
+                        transport: browserRuntimeTransport(preparedSession, placement.transport),
+                        ...(linkedComputer ? { linkedComputer } : {}),
+                        ...(networkRoute ? { networkRoute } : {}),
+                        ...(request.initialUrl ? { initialUrl: request.initialUrl } : {}),
+                        ...(restore ? { restore } : {}),
+                      }),
+                  ),
+              );
+              await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
+                () => placement,
+              );
             } catch (error) {
               if (
                 error instanceof BrowserControlTransportError ||
@@ -359,7 +485,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   grant,
                   workspaceId,
                   prepared.session.id,
-                  placement.placement,
+                  placement.controllerHostSandboxGroupId,
                 ).catch(() => undefined);
               }
               return failed;
@@ -386,6 +512,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         },
       );
       const parsed = BrowserSessionMutationResponse.parse(response);
+      observeLifecycleResult(deps.observability, startedAtMs, parsed);
       return context.json(
         parsed,
         parsed.operation.state === "completed" && !parsed.operation.replayed ? 201 : 200,
@@ -435,7 +562,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         browserSessionId,
         "session.control",
         "browser.control",
-        async ({ sessionClient }) => await sessionClient.openTarget(request.url),
+        async ({ sessionClient }) =>
+          BrowserObservation.parse(await sessionClient.openTarget(request.url)),
       );
       return context.json(result, 201);
     },
@@ -457,20 +585,814 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         browserSessionId,
         "session.control",
         "browser.control",
-        async ({ sessionClient }) => await sessionClient.selectTarget(targetId),
+        async ({ sessionClient }) =>
+          BrowserObservation.parse(await sessionClient.selectTarget(targetId)),
+      );
+      return context.json(result);
+    },
+  );
+
+  app.delete(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:control",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.control",
+        "browser.control",
+        async ({ sessionClient, binding }) =>
+          BrowserTargetListResponse.parse({
+            browserSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            targets: await sessionClient.closeTarget(targetId),
+          }),
+      );
+      return context.json(result);
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/downloads",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.listDownloads(),
+      );
+      return context.json(BrowserDownloadListResponse.parse(result));
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/downloads/:downloadId",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const downloadId = requireUuidParam(context, "downloadId");
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.download(downloadId),
+      );
+      return context.json(BrowserDownload.parse(result));
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/downloads/:downloadId/save",
+    async (context) => {
+      const workspaceId = context.req.param("workspaceId") ?? "";
+      const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
+      await requireAccessGrant(context, deps, workspaceId, "files:upload");
+      const browserSessionId = requireUuidParam(context, "browserSessionId");
+      const downloadId = requireUuidParam(context, "downloadId");
+      const request = await parseJsonBody(context, BrowserDownloadSaveRequest);
+      const objectStorage = deps.objectStorage;
+      const identity = {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+        browserSessionId,
+        downloadId,
+        request,
+      };
+
+      try {
+        let save = await findBrowserDownloadSave(deps.db, identity);
+        if (save?.response) {
+          return context.json(BrowserDownloadSaveResponse.parse(save.response), 200);
+        }
+        if (!objectStorage) {
+          throw new HTTPException(503, { message: "object storage is not configured" });
+        }
+        if (save && isTerminalOperation(save.state)) {
+          throw new InteractionResourceStateError(
+            `Browser download save is ${save.state.replace("_", " ")}`,
+          );
+        }
+
+        if (!save) {
+          const source = await withActiveBrowserController(
+            context,
+            grant,
+            workspaceId,
+            browserSessionId,
+            "session.control",
+            "browser.read",
+            async ({ sessionClient, record, binding }) => {
+              const download = await sessionClient.download(downloadId);
+              if (
+                download.status !== "completed" ||
+                !download.sha256 ||
+                download.controllerGeneration !== binding.controllerGeneration
+              ) {
+                throw new InteractionResourceStateError("Browser download is not ready to save");
+              }
+              return { download, sourceSessionId: record.sourceSessionId };
+            },
+          );
+          if (source.download.receivedBytes > objectStorage.maxSinglePutSizeBytes) {
+            throw new HTTPException(413, {
+              message: `browser download exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes`,
+            });
+          }
+          const fileId = randomUUID();
+          const safeFilename = sanitizeFilename(source.download.filename);
+          save = await prepareBrowserDownloadSave(deps.db, {
+            ...identity,
+            sourceSessionId: source.sourceSessionId,
+            download: source.download,
+            fileId,
+            safeFilename,
+            contentType: "application/octet-stream",
+            bucket: objectStorage.bucket,
+            objectKey: `workspaces/${workspaceId}/files/${fileId}/original/${safeFilename}`,
+            uploadExpiresAt: new Date(
+              Date.now() + BROWSER_WORKSPACE_FILE_AUTHORITY_TTL_SECONDS * 1_000,
+            ),
+          });
+        }
+
+        if (save.download.receivedBytes > objectStorage.maxSinglePutSizeBytes) {
+          throw new HTTPException(413, {
+            message: `browser download exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes`,
+          });
+        }
+        await requireLimit(deps, {
+          accountId: grant.accountId,
+          workspaceId,
+          action: "file:upload",
+          quantity: save.download.receivedBytes,
+        });
+
+        let upload = await getFileUpload(deps.db, workspaceId, save.uploadId);
+        if (!upload || upload.file.id !== save.fileId || upload.file.objectKey !== save.objectKey) {
+          throw new InteractionResourceStateError("Browser download file authority is unavailable");
+        }
+        const controllerRecord = await getBrowserSessionControlRecord(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          browserSessionId,
+        });
+        if (upload.status === "pending") {
+          if (save.state !== "prepared") {
+            throw new InteractionResourceStateError(
+              "Browser download save was dispatched before its bytes were published",
+            );
+          }
+          const put = await objectStorage.createPutUrl({
+            key: save.objectKey,
+            contentType: save.contentType,
+            sha256: save.download.sha256,
+            expiresInSeconds: BROWSER_WORKSPACE_FILE_AUTHORITY_TTL_SECONDS,
+            audience: signedUrlAudienceForPlacement(controllerRecord.session.placement),
+          });
+          save = await prepareBrowserDownloadSave(deps.db, {
+            ...identity,
+            sourceSessionId: save.sourceSessionId,
+            download: save.download,
+            fileId: save.fileId,
+            safeFilename: save.safeFilename,
+            contentType: save.contentType,
+            bucket: upload.file.bucket,
+            objectKey: save.objectKey,
+            uploadExpiresAt: put.expiresAt,
+          });
+          const preparedSave = save;
+          const receipt = await withActiveBrowserController(
+            context,
+            grant,
+            workspaceId,
+            browserSessionId,
+            "session.control",
+            "browser.control",
+            async ({ sessionClient, record, binding }) => {
+              if (
+                record.sourceSessionId !== preparedSave.sourceSessionId ||
+                binding.controllerGeneration !== preparedSave.controllerGeneration
+              ) {
+                throw new InteractionResourceStateError(
+                  "Browser download belongs to a stale controller",
+                );
+              }
+              const current = await sessionClient.download(downloadId);
+              assertBrowserDownloadSaveSource(current, preparedSave.download);
+              return await sessionClient.exportDownload(downloadId, {
+                operationId: request.operationId,
+                downloadId,
+                upload: {
+                  url: put.url,
+                  requiredHeaders: put.requiredHeaders,
+                  expiresAt: put.expiresAt.toISOString(),
+                },
+              });
+            },
+          );
+          if (
+            receipt.sizeBytes !== save.download.receivedBytes ||
+            receipt.sha256 !== save.download.sha256
+          ) {
+            throw new BrowserControlProtocolError(
+              "browser controller returned another download export",
+            );
+          }
+          upload = await finalizeBrowserDownloadFile(deps, grant, workspaceId, save.uploadId);
+        } else if (upload.status === "completed" && upload.file.status === "ready") {
+          await recordBrowserDownloadFileUsage(deps, grant, workspaceId, upload.file);
+        } else {
+          throw new InteractionResourceStateError(
+            `Browser download file upload is ${upload.status.replace("_", " ")}`,
+          );
+        }
+
+        if (upload.file.status !== "ready") {
+          throw new InteractionResourceStateError("Browser download file is not ready");
+        }
+        const get = await objectStorage.createGetUrl({
+          key: upload.file.objectKey,
+          expiresInSeconds: BROWSER_WORKSPACE_FILE_AUTHORITY_TTL_SECONDS,
+          audience: signedUrlAudienceForPlacement(controllerRecord.session.placement),
+        });
+        const sourceSession = await requireSourceSession(deps, workspaceId, save.sourceSessionId);
+        await authorizeSourceSession(deps, grant, save.sourceSessionId, "session.control");
+        const dispatched = await dispatchBrowserDownloadSave(deps.db, identity);
+        const imported = await withChannelA(
+          channelServices,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            session: sourceSession,
+            subjectId: grant.subjectId,
+            waitSignal: context.req.raw.signal,
+            operation: "browser.download.save",
+          },
+          async ({ service }) =>
+            await service.importWorkspaceFile({
+              operationId: request.operationId,
+              destinationPath: save.destinationPath,
+              overwrite: save.overwrite,
+              mayReplaceExisting: save.overwrite && dispatched.dispatchedNow,
+              sizeBytes: save.download.receivedBytes,
+              sha256: save.download.sha256!,
+              source: {
+                url: get.url,
+                expiresAt: get.expiresAt.toISOString(),
+              },
+            }),
+        );
+        if (
+          imported.destinationPath !== save.destinationPath ||
+          imported.sizeBytes !== save.download.receivedBytes ||
+          imported.sha256 !== save.download.sha256
+        ) {
+          await settleBrowserDownloadSaveFailure(deps.db, {
+            ...identity,
+            state: "outcome_unknown",
+            errorCode: "workspace_import_receipt_mismatch",
+          });
+          throw new InteractionResourceStateError(
+            "Browser download workspace import outcome is unknown",
+          );
+        }
+        const response = await completeBrowserDownloadSave(deps.db, identity);
+        return context.json(
+          BrowserDownloadSaveResponse.parse(response),
+          response.replayed ? 200 : 201,
+        );
+      } catch (error) {
+        throw browserRouteError(error);
+      }
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/observation",
+    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.observe(targetId),
       );
       return context.json(result);
     },
   );
 
-  app.delete(
-    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId",
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/actions",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:control",
+      );
+      const request = await parseJsonBody(context, BrowserActionRequest);
+      const workspaceFileIds = browserUploadFileIds(request.action);
+      if (workspaceFileIds.length > 0) {
+        await requireAccessGrant(context, deps, workspaceId, "files:read");
+      }
+      const startedAtMs = performance.now();
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.control",
+        "browser.action",
+        async ({ sessionClient, binding, record }) => {
+          const command = BrowserActionCommand.parse({
+            protocolVersion: BROWSER_CONTROL_PROTOCOL_VERSION,
+            operationId: request.operationId,
+            browserSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            targetId: request.targetId,
+            expectedTargetGeneration: request.expectedTargetGeneration,
+            expectedDocumentGeneration: request.expectedDocumentGeneration,
+            expectedFrameId: request.expectedFrameId,
+            actor: interactionActorForGrant(grant),
+            observationMode: request.observationMode,
+            action: request.action,
+          });
+          if (workspaceFileIds.length > 0) {
+            let alreadyAdmitted = false;
+            try {
+              await sessionClient.receipt(request.operationId);
+              alreadyAdmitted = true;
+            } catch (error) {
+              if (!(error instanceof BrowserControlRequestError && error.status === 404)) {
+                throw error;
+              }
+            }
+            if (!alreadyAdmitted) {
+              if (!deps.objectStorage) {
+                throw new HTTPException(503, {
+                  message: "object storage is not configured",
+                });
+              }
+              const files = await getFiles(deps.db, workspaceId, workspaceFileIds);
+              const byId = new Map(files.map((file) => [file.id, file]));
+              const ordered = workspaceFileIds.map((fileId) => byId.get(fileId));
+              if (ordered.some((file) => !file)) {
+                throw new HTTPException(404, { message: "workspace file not found" });
+              }
+              if (ordered.some((file) => file!.status !== "ready")) {
+                throw new HTTPException(409, { message: "workspace file is not ready" });
+              }
+              const authorities = await Promise.all(
+                ordered.map(async (file) => {
+                  const signed = await deps.objectStorage!.createGetUrl({
+                    key: file!.objectKey,
+                    expiresInSeconds: BROWSER_WORKSPACE_FILE_AUTHORITY_TTL_SECONDS,
+                    audience: signedUrlAudienceForPlacement(record.session.placement),
+                  });
+                  return {
+                    fileId: file!.id,
+                    safeFilename: browserUploadFilename(file!.safeFilename),
+                    sizeBytes: file!.sizeBytes,
+                    sha256: browserUploadSha256(file!.sha256),
+                    download: {
+                      url: signed.url,
+                      expiresAt: signed.expiresAt.toISOString(),
+                    },
+                  };
+                }),
+              );
+              await sessionClient.stageWorkspaceFiles({
+                operationId: request.operationId,
+                files: authorities,
+              });
+            }
+          }
+          return await sessionClient.action(command);
+        },
+      );
+      observeBrowserActionResult(deps.observability, startedAtMs, request, result);
+      return context.json(result);
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/clipboard",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.readClipboard(),
+      );
+      return context.json(result);
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async () =>
+          await listAuthRuns(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+            includeSettled: context.req.query("includeSettled") === "true",
+          }),
+      );
+      return context.json(result);
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:control",
+      );
+      const request = await parseJsonBody(context, StartAuthRunRequest);
+      const actor = interactionActorForGrant(grant);
+      const startedAtMs = performance.now();
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.control",
+        "browser.control",
+        async ({ sessionClient, binding }) => {
+          const observation = await sessionClient.observe(request.targetId);
+          if (
+            observation.target.targetGeneration !== request.expectedTargetGeneration ||
+            observation.target.documentGeneration !== request.expectedDocumentGeneration
+          ) {
+            throw new InteractionResourceConflictError(
+              "Auth run does not match the currently observed browser document",
+            );
+          }
+          return await startAuthRun(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            browserSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            originatingSessionId:
+              actor.kind === "agent" && actor.sessionId ? actor.sessionId : null,
+            ...request,
+          });
+        },
+      );
+      observeAuthMutation(deps.observability, startedAtMs, result);
+      return context.json(result, result.replayed ? 200 : 201);
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs/:authRunId",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const authRunId = requireUuidParam(context, "authRunId");
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async () => {
+          const run = await getAuthRun(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            authRunId,
+          });
+          assertAuthRunBrowser(run.browserSessionId, browserSessionId);
+          return run;
+        },
+      );
+      return context.json(result);
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs/:authRunId/report",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:control",
+      );
+      const authRunId = requireUuidParam(context, "authRunId");
+      const request = await parseJsonBody(context, ReportAuthRunRequest);
+      const startedAtMs = performance.now();
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.control",
+        "browser.control",
+        async ({ binding }) => {
+          const current = await getAuthRun(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            authRunId,
+          });
+          assertAuthRunBrowser(current.browserSessionId, browserSessionId);
+          return await reportAuthRun(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            authRunId,
+            controllerGeneration: binding.controllerGeneration,
+            ...request,
+          });
+        },
+      );
+      observeAuthMutation(deps.observability, startedAtMs, result);
+      return context.json(result);
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs/:authRunId/protected-fill",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:control",
+      );
+      const authRunId = requireUuidParam(context, "authRunId");
+      const request = await parseJsonBody(context, ProtectedAuthFillRequest);
+      const startedAtMs = performance.now();
+      try {
+        const replay = await getProtectedAuthFillPreparation(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          actorSubjectId: grant.subjectId,
+          authRunId,
+          ...request,
+        });
+        if (replay?.response) {
+          const record = await getBrowserSessionControlRecord(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+          });
+          await authorizeSourceSession(deps, grant, record.sourceSessionId, "session.control");
+          assertAuthRunBrowser(replay.run.browserSessionId, browserSessionId);
+          const response = ProtectedAuthFillResponse.parse(replay.response);
+          observeAuthMutation(deps.observability, startedAtMs, response);
+          return context.json(response);
+        }
+      } catch (error) {
+        throw browserRouteError(error);
+      }
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.control",
+        "browser.control",
+        async ({ sessionClient, binding, record }) => {
+          const actor = interactionActorForGrant(grant);
+          const scope = {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            authRunId,
+          };
+          let preparation = await getProtectedAuthFillPreparation(deps.db, {
+            ...scope,
+            ...request,
+          });
+          let credential: Awaited<ReturnType<typeof loadConnectionCredentialForBroker>> = null;
+          if (!preparation) {
+            const run = await getAuthRun(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              authRunId,
+            });
+            assertAuthRunBrowser(run.browserSessionId, browserSessionId);
+            const connection = await getSiteAuthConnection(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              siteAuthConnectionId: run.siteAuthConnectionId,
+            });
+            const authority = connection.authorities.find(
+              (candidate) => candidate.id === request.authorityId,
+            );
+            if (!authority) {
+              throw new InteractionResourceStateError("Auth authority is not configured");
+            }
+            if (authority.kind === "external_provider") {
+              throw new InteractionResourceStateError(
+                "External auth providers cannot use protected field fill",
+              );
+            }
+            if (authority.kind === "connection_fields") {
+              credential = await loadBoundBrowserCredential(deps, grant, workspaceId, authority);
+            }
+            preparation = await prepareProtectedAuthFill(deps.db, {
+              ...scope,
+              ...request,
+              credentialVersion: credential?.version ?? null,
+            });
+          }
+          assertAuthRunBrowser(preparation.run.browserSessionId, browserSessionId);
+          if (preparation.run.controllerGeneration !== binding.controllerGeneration) {
+            throw new InteractionResourceConflictError(
+              "Auth run belongs to a stale browser controller",
+            );
+          }
+          if (preparation.response) return preparation.response;
+          if (
+            preparation.operationState === "failed" ||
+            preparation.operationState === "outcome_unknown"
+          ) {
+            throw new InteractionResourceStateError(
+              `Protected-fill operation is ${preparation.operationState.replace("_", " ")}`,
+            );
+          }
+          if (preparation.authority.kind === "human") {
+            if (preparation.operationState !== "prepared") {
+              throw new InteractionResourceStateError(
+                "Human protected-fill operation entered an invalid dispatch state",
+              );
+            }
+            return await completeProtectedAuthFill(deps.db, {
+              ...scope,
+              operationId: request.operationId,
+              status: "needs_human",
+              intervention: {
+                originatingSessionId: record.sourceSessionId,
+                originatingTurnId: actor.kind === "agent" ? (actor.turnId ?? null) : null,
+                originatingAttemptId: actor.kind === "agent" ? (actor.attemptId ?? null) : null,
+                originatingToolOperationId:
+                  actor.kind === "agent" && actor.attemptId ? request.operationId : null,
+                kind: preparation.authority.fields.some((field) => field.purpose === "totp")
+                  ? "mfa"
+                  : "manual_login",
+                reason: "Sign in or complete authentication in this browser tab.",
+                expiresInSeconds: 900,
+              },
+            });
+          }
+          if (preparation.authority.kind === "external_provider") {
+            throw new InteractionResourceStateError(
+              "External auth providers cannot use protected field fill",
+            );
+          }
+
+          if (preparation.operationState === "dispatched") {
+            try {
+              const receipt = await sessionClient.protectedAuthReceipt(request.operationId);
+              return await settleProtectedAuthReceipt({
+                deps,
+                scope,
+                receipt,
+              });
+            } catch (error) {
+              if (
+                error instanceof BrowserControlRequestError &&
+                error.error.code === "resource_not_found"
+              ) {
+                await markProtectedAuthFillOutcomeUnknown(deps.db, {
+                  ...scope,
+                  operationId: request.operationId,
+                  errorCode: "controller_receipt_missing",
+                });
+                throw new InteractionResourceStateError(
+                  "Protected-fill outcome is unknown after controller recovery",
+                );
+              }
+              throw error;
+            }
+          }
+
+          credential ??= await loadBoundBrowserCredential(
+            deps,
+            grant,
+            workspaceId,
+            preparation.authority,
+          );
+          if (credential.version !== preparation.credentialVersion) {
+            throw new InteractionResourceConflictError(
+              "Credential changed after protected fill was prepared; use a new operation id",
+            );
+          }
+          const fields = resolveProtectedAuthFieldValues({
+            authority: preparation.authority,
+            requestedFields: request.fields,
+            credential: credential.credential,
+          });
+          await dispatchProtectedAuthFill(deps.db, {
+            ...scope,
+            operationId: request.operationId,
+          });
+          const receipt = await sessionClient.protectedAuthFill(
+            BrowserProtectedAuthFillCommand.parse({
+              protocolVersion: BROWSER_CONTROL_PROTOCOL_VERSION,
+              operationId: request.operationId,
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+              targetId: preparation.run.targetId,
+              expectedTargetGeneration: request.expectedTargetGeneration,
+              expectedDocumentGeneration: request.expectedDocumentGeneration,
+              expectedFrameId: request.expectedFrameId,
+              actor,
+              authorityId: preparation.authority.id,
+              credentialVersion: preparation.credentialVersion,
+              allowedOrigins: preparation.origins,
+              fields,
+              submit: request.submit,
+            }),
+          );
+          return await settleProtectedAuthReceipt({ deps, scope, receipt });
+        },
+      );
+      const response = ProtectedAuthFillResponse.parse(result);
+      observeAuthMutation(deps.observability, startedAtMs, response);
+      return context.json(response);
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs/:authRunId/external-auth",
     async (context) => {
       const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
         context,
         "sessions:control",
       );
-      const targetId = requireOpaqueParam(context, "targetId");
+      const authRunId = requireUuidParam(context, "authRunId");
+      const request = await parseJsonBody(context, ExternalAuthRunRequest);
+      const startedAtMs = performance.now();
+      try {
+        const replay = await getExternalAuthPreparation(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          actorSubjectId: grant.subjectId,
+          authRunId,
+          ...request,
+        });
+        if (replay?.response) {
+          const record = await getBrowserSessionControlRecord(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+          });
+          await authorizeSourceSession(deps, grant, record.sourceSessionId, "session.control");
+          assertAuthRunBrowser(replay.run.browserSessionId, browserSessionId);
+          const response = ExternalAuthRunResponse.parse(replay.response);
+          observeAuthMutation(deps.observability, startedAtMs, response);
+          return context.json(response);
+        }
+      } catch (error) {
+        throw browserRouteError(error);
+      }
       const result = await withActiveBrowserController(
         context,
         grant,
@@ -478,46 +1400,179 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         browserSessionId,
         "session.control",
         "browser.control",
-        async ({ sessionClient, binding }) =>
-          BrowserTargetListResponse.parse({
-            browserSessionId,
-            controllerGeneration: binding.controllerGeneration,
-            targets: await sessionClient.closeTarget(targetId),
-          }),
+        async ({ sessionClient, binding, record }) => {
+          const actor = interactionActorForGrant(grant);
+          const scope = {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            authRunId,
+          };
+          let preparation = await getExternalAuthPreparation(deps.db, {
+            ...scope,
+            ...request,
+          });
+          preparation ??= await prepareExternalAuth(deps.db, {
+            ...scope,
+            ...request,
+          });
+          assertAuthRunBrowser(preparation.run.browserSessionId, browserSessionId);
+          if (preparation.run.controllerGeneration !== binding.controllerGeneration) {
+            throw new InteractionResourceConflictError(
+              "Auth run belongs to a stale browser controller",
+            );
+          }
+          if (preparation.response) return preparation.response;
+          if (
+            preparation.operationState === "failed" ||
+            preparation.operationState === "outcome_unknown"
+          ) {
+            throw new InteractionResourceStateError(
+              `External-auth operation is ${preparation.operationState.replace("_", " ")}`,
+            );
+          }
+          if (preparation.operationState === "prepared") {
+            await dispatchExternalAuth(deps.db, {
+              ...scope,
+              operationId: request.operationId,
+            });
+          }
+          const providerResult = await sessionClient.externalAuth(
+            BrowserExternalAuthCommand.parse({
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+              operationId: request.operationId,
+              authRunId,
+              adapterId: preparation.authority.adapterId,
+              connectionId: preparation.authority.connectionId,
+              action: request.action,
+            }),
+          );
+          if (providerResult.interactiveUrl !== null) {
+            throw new BrowserControlProtocolError(
+              "provider exposed a hosted login URL outside the human-only endpoint",
+            );
+          }
+          let target:
+            | { id: string; targetGeneration: string; documentGeneration: string | null }
+            | undefined;
+          if (providerResult.state === "authenticated") {
+            const targets = await sessionClient.listTargets();
+            const selected = targets.find((candidate) => candidate.selected) ?? targets[0];
+            if (!selected) {
+              throw new BrowserControlProtocolError(
+                "authenticated provider browser returned no current target",
+              );
+            }
+            const observation = await sessionClient.observe(selected.id);
+            target = {
+              id: observation.target.id,
+              targetGeneration: observation.target.targetGeneration,
+              documentGeneration: observation.target.documentGeneration,
+            };
+          }
+          return await completeExternalAuth(deps.db, {
+            ...scope,
+            operationId: request.operationId,
+            result: providerResult,
+            ...(target ? { target } : {}),
+            ...(providerResult.state === "needs_human"
+              ? {
+                  intervention: {
+                    originatingSessionId: record.sourceSessionId,
+                    originatingTurnId: actor.kind === "agent" ? (actor.turnId ?? null) : null,
+                    originatingAttemptId: actor.kind === "agent" ? (actor.attemptId ?? null) : null,
+                    originatingToolOperationId:
+                      actor.kind === "agent" && actor.attemptId ? request.operationId : null,
+                    expiresInSeconds: 1_200,
+                  },
+                }
+              : {}),
+          });
+        },
       );
-      return context.json(result);
+      const response = ExternalAuthRunResponse.parse(result);
+      observeAuthMutation(deps.observability, startedAtMs, response);
+      return context.json(response);
     },
   );
 
-  app.get(
-    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/observation",
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs/:authRunId/external-auth/interactive",
     async (context) => {
       const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
         context,
-        "sessions:read",
+        "sessions:control",
       );
-      const targetId = requireOpaqueParam(context, "targetId");
+      if (grant.principalKind !== "human_session") {
+        throw new HTTPException(403, {
+          message: "hosted login flows can only be opened by an interactive user",
+        });
+      }
+      const authRunId = requireUuidParam(context, "authRunId");
+      const request = await parseJsonBody(context, ExternalAuthInteractiveRequest);
       const result = await withActiveBrowserController(
         context,
         grant,
         workspaceId,
         browserSessionId,
-        "session.read",
-        "browser.read",
-        async ({ sessionClient }) => await sessionClient.observe(targetId),
+        "session.control",
+        "browser.control",
+        async ({ sessionClient, binding }) => {
+          const resolved = await getExternalAuthInteractiveContext(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            authRunId,
+            ...request,
+          });
+          assertAuthRunBrowser(resolved.run.browserSessionId, browserSessionId);
+          if (resolved.run.controllerGeneration !== binding.controllerGeneration) {
+            throw new InteractionResourceConflictError(
+              "Hosted login belongs to a stale browser controller",
+            );
+          }
+          const providerResult = await sessionClient.externalAuth(
+            BrowserExternalAuthCommand.parse({
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+              operationId: request.operationId,
+              authRunId,
+              adapterId: resolved.authority.adapterId,
+              connectionId: resolved.authority.connectionId,
+              action: "interactive",
+            }),
+          );
+          if (
+            providerResult.state !== "needs_human" ||
+            !providerResult.externalAction ||
+            !providerResult.interactiveUrl
+          ) {
+            throw new InteractionResourceStateError(
+              "Hosted login is no longer waiting for human input",
+            );
+          }
+          return ExternalAuthInteractiveResponse.parse({
+            authRunId,
+            url: providerResult.interactiveUrl,
+            expiresAt: providerResult.externalAction.expiresAt,
+          });
+        },
       );
-      return context.json(result);
+      return context.json(ExternalAuthInteractiveResponse.parse(result));
     },
   );
 
   app.post(
-    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/actions",
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/auth-runs/:authRunId/verify",
     async (context) => {
       const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
         context,
         "sessions:control",
       );
-      const request = await parseJsonBody(context, BrowserActionRequest);
+      const authRunId = requireUuidParam(context, "authRunId");
+      const request = await parseJsonBody(context, VerifyAuthRunRequest);
+      const startedAtMs = performance.now();
       const result = await withActiveBrowserController(
         context,
         grant,
@@ -525,22 +1580,29 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         browserSessionId,
         "session.control",
         "browser.control",
-        async ({ sessionClient, binding }) =>
-          await sessionClient.action(
-            BrowserActionCommand.parse({
-              protocolVersion: BROWSER_CONTROL_PROTOCOL_VERSION,
-              operationId: request.operationId,
-              browserSessionId,
-              controllerGeneration: binding.controllerGeneration,
-              targetId: request.targetId,
-              expectedTargetGeneration: request.expectedTargetGeneration,
-              expectedDocumentGeneration: request.expectedDocumentGeneration,
-              expectedFrameId: request.expectedFrameId,
-              actor: interactionActorForGrant(grant),
-              action: request.action,
-            }),
-          ),
+        async ({ sessionClient, binding }) => {
+          const run = await getAuthRun(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            authRunId,
+          });
+          assertAuthRunBrowser(run.browserSessionId, browserSessionId);
+          const observation = await sessionClient.observe(run.targetId);
+          return await verifyAuthRun(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+            authRunId,
+            controllerGeneration: binding.controllerGeneration,
+            targetId: observation.target.id,
+            targetGeneration: observation.target.targetGeneration,
+            documentGeneration: observation.target.documentGeneration,
+            url: observation.target.url,
+            ...request,
+          });
+        },
       );
+      observeAuthMutation(deps.observability, startedAtMs, result);
       return context.json(result);
     },
   );
@@ -602,6 +1664,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         context,
         "stream:view",
       );
+      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
       const request = await parseJsonBody(context, BrowserSessionAttachmentRequest);
       const result = await withActiveBrowserController(
         context,
@@ -611,7 +1674,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         "session.viewer.read",
         "browser.attach",
         async ({ client, sessionClient, record, binding, placement }) => {
-          await sessionClient.observe(request.targetId);
+          if (origin) await client.addAllowedOrigins([origin]);
+          const targets = await sessionClient.listTargets();
+          if (!targets.some((target) => target.id === request.targetId)) {
+            throw new HTTPException(404, { message: "browser target does not exist" });
+          }
           const grantId = randomUUID();
           const expiresAt = new Date(Date.now() + request.expiresInSeconds * 1_000).toISOString();
           const rootSecret = browserAuthorityRoot(deps);
@@ -639,7 +1706,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             browserSessionId,
             controllerGeneration: binding.controllerGeneration,
           };
-          await client.createViewGrant(reference, { grantId, token, expiresAt });
+          await client.createViewGrant(reference, {
+            grantId,
+            token,
+            expiresAt,
+          });
           const relayed = await client.openRelayedFrameStream({
             reference,
             targetId: request.targetId,
@@ -672,7 +1743,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               })()
             : {
                 kind: "direct_websocket" as const,
-                url: await client.frameStreamUrl(reference, request.targetId),
+                url: await client.frameStreamUrl(reference, request.targetId, request.stream),
                 protocols: [
                   BROWSER_CONTROL_WEBSOCKET_PROTOCOL,
                   `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
@@ -714,6 +1785,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             alive: true,
           });
         },
+        false,
       );
       return context.json(result);
     },
@@ -726,6 +1798,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, PublishBrowserRevisionRequest);
+      const startedAtMs = performance.now();
       try {
         const record = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -745,7 +1818,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         };
         const prepared = await prepareBrowserRevisionPublication(deps.db, publicationInput);
         if (prepared.kind === "completed") {
-          return context.json(PublishBrowserRevisionResponse.parse(prepared.response), 200);
+          const parsed = PublishBrowserRevisionResponse.parse(prepared.response);
+          observeBrowserRevisionPublication(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
         const objectStorage = deps.objectStorage;
         if (!objectStorage) {
@@ -785,15 +1860,20 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               objectKey,
             });
             try {
-              const signed = await objectStorage.createPutUrl({
-                key: objectKey,
-                contentType: BROWSER_STATE_ARTIFACT_CONTENT_TYPE,
-              });
               const dispatched = await dispatchBrowserRevisionPublication(deps.db, {
                 ...publicationInput,
                 controllerGeneration: binding.controllerGeneration,
+                stateUpload: {
+                  objectKey,
+                  cleanupAfter: new Date(Date.now() + BROWSER_STATE_UPLOAD_CLEANUP_GRACE_MS),
+                },
               });
               if (dispatched.kind === "completed") return dispatched.response;
+              const signed = await objectStorage.createPutUrl({
+                key: objectKey,
+                contentType: BROWSER_STATE_ARTIFACT_CONTENT_TYPE,
+                audience: signedUrlAudienceForPlacement(activeRecord.session.placement),
+              });
 
               let receipt;
               try {
@@ -863,6 +1943,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           },
         );
         const parsed = PublishBrowserRevisionResponse.parse(response);
+        observeBrowserRevisionPublication(deps.observability, startedAtMs, parsed);
         return context.json(parsed, parsed.replayed ? 200 : 201);
       } catch (error) {
         throw browserRouteError(error);
@@ -877,6 +1958,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
+      const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
@@ -885,6 +1967,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           browserSessionId,
         });
         await authorizeSourceSession(deps, grant, before.sourceSessionId, "session.control");
+        if (!before.session.capabilities.privateCheckpoint) {
+          throw new BrowserControlUnsupportedError(
+            "this browser placement does not support private checkpoint suspension",
+          );
+        }
         browserAuthorityRoot(deps);
         if (!deps.objectStorage) {
           throw new HTTPException(503, {
@@ -906,21 +1993,22 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               workspaceId,
               browserSessionId,
             );
-            return context.json(
-              BrowserSessionMutationResponse.parse({
-                session: (
-                  await getBrowserSessionControlRecord(deps.db, {
-                    accountId: grant.accountId,
-                    workspaceId,
-                    browserSessionId,
-                  })
-                ).session,
-                operation: prepared.operation,
-              }),
-              200,
-            );
+            const parsed = BrowserSessionMutationResponse.parse({
+              session: (
+                await getBrowserSessionControlRecord(deps.db, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  browserSessionId,
+                })
+              ).session,
+              operation: prepared.operation,
+            });
+            observeLifecycleResult(deps.observability, startedAtMs, parsed);
+            return context.json(parsed, 200);
           }
-          return context.json(BrowserSessionMutationResponse.parse(prepared), 200);
+          const parsed = BrowserSessionMutationResponse.parse(prepared);
+          observeLifecycleResult(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
 
         const record = await getBrowserSessionControlRecord(deps.db, {
@@ -958,34 +2046,52 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               objectKey,
             });
             try {
-              const signed = await objectStorage.createPutUrl({
-                key: objectKey,
-                contentType: BROWSER_STATE_ARTIFACT_CONTENT_TYPE,
-              });
               await dispatchBrowserSessionOperation(deps.db, {
                 accountId: grant.accountId,
                 workspaceId,
                 operationId: request.operationId,
                 browserSessionId,
                 controllerGeneration: binding.controllerGeneration,
+                stateUpload: {
+                  objectKey,
+                  cleanupAfter: new Date(Date.now() + BROWSER_STATE_UPLOAD_CLEANUP_GRACE_MS),
+                },
+              });
+              const signed = await objectStorage.createPutUrl({
+                key: objectKey,
+                contentType: BROWSER_STATE_ARTIFACT_CONTENT_TYPE,
+                audience: signedUrlAudienceForPlacement(record.session.placement),
               });
               const client = await provisionController(deps, grant, record, placement, origin);
               let receipt: PlacementBrowserStateCaptureReceipt;
               try {
-                receipt = await client.captureState({
-                  browserSessionId,
-                  controllerGeneration: binding.controllerGeneration,
-                  operationId: request.operationId,
-                  objectKey,
-                  afterCapture: "stop",
-                  dataKey,
-                  aad,
-                  upload: {
-                    url: signed.url,
-                    requiredHeaders: signed.requiredHeaders,
-                    expiresAt: signed.expiresAt.toISOString(),
+                receipt = await withInteractionHolderHeartbeat(
+                  deps,
+                  {
+                    grant,
+                    workspaceId,
+                    sandboxGroupId: record.controllerHostSandboxGroupId,
+                    holderId: interactionHolderId(browserSessionId),
+                    operationId: request.operationId,
+                    resourceId: browserSessionId,
+                    controllerGeneration: binding.controllerGeneration,
                   },
-                });
+                  async () =>
+                    await client.captureState({
+                      browserSessionId,
+                      controllerGeneration: binding.controllerGeneration,
+                      operationId: request.operationId,
+                      objectKey,
+                      afterCapture: "stop",
+                      dataKey,
+                      aad,
+                      upload: {
+                        url: signed.url,
+                        requiredHeaders: signed.requiredHeaders,
+                        expiresAt: signed.expiresAt.toISOString(),
+                      },
+                    }),
+                );
               } catch (error) {
                 const failed = await settleBrowserSessionSuspensionCaptureFailure(
                   deps,
@@ -1043,7 +2149,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                 grant,
                 workspaceId,
                 browserSessionId,
-                record.session.placement,
+                record.controllerHostSandboxGroupId,
               );
               return BrowserSessionMutationResponse.parse({
                 session: (
@@ -1062,7 +2168,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             }
           },
         );
-        return context.json(BrowserSessionMutationResponse.parse(response), 200);
+        const parsed = BrowserSessionMutationResponse.parse(response);
+        observeLifecycleResult(deps.observability, startedAtMs, parsed);
+        return context.json(parsed, 200);
       } catch (error) {
         throw browserRouteError(error);
       }
@@ -1076,6 +2184,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
+      const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
       let restore: RestorePlacementBrowserStateInput | null = null;
       try {
@@ -1098,7 +2207,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             browserSessionId,
           });
         }
-        browserAuthorityRoot(deps);
+        const authority = browserAuthorityRoot(deps);
         const prepared = await prepareBrowserSessionResume(deps.db, {
           accountId: grant.accountId,
           workspaceId,
@@ -1107,7 +2216,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           actorSubjectId: grant.subjectId,
         });
         if (isTerminalOperation(prepared.operation.state)) {
-          return context.json(BrowserSessionMutationResponse.parse(prepared), 200);
+          const parsed = BrowserSessionMutationResponse.parse(prepared);
+          observeLifecycleResult(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
 
         const privateCheckpoint = await getBrowserPrivateCheckpointAuthority(deps.db, {
@@ -1156,6 +2267,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           "browser.resume",
           context.req.raw.signal,
           async (placement) => {
+            const networkRoute = await resolveBrowserNetworkRouteLaunch({
+              deps,
+              grant,
+              workspaceId,
+              browserSessionId,
+              operationId: request.operationId,
+              rootSecret: authority,
+              placement: placement.placement,
+            });
             const interactionHeld = await ensureInteractionHolder(
               deps,
               grant,
@@ -1171,7 +2291,18 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               browserSessionId,
               request.operationId,
               placement.placementInstanceId,
-            );
+            ).catch(async (error: unknown) => {
+              if (interactionHeld) {
+                await releaseInteractionHolder(
+                  deps,
+                  grant,
+                  workspaceId,
+                  browserSessionId,
+                  placement.controllerHostSandboxGroupId,
+                ).catch(() => undefined);
+              }
+              throw error;
+            });
             const controllerGeneration = requireOperationGeneration(record);
             const linkedComputer = await requireLinkedComputerBinding(
               deps,
@@ -1180,14 +2311,14 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               placement,
             );
             const adminToken = deriveBrowserControllerAdminToken({
-              rootSecret: browserAuthorityRoot(deps),
+              rootSecret: authority,
               accountId: grant.accountId,
               workspaceId,
               placement: placement.placement,
               placementInstanceId: placement.placementInstanceId,
             });
             const tokens = deriveBrowserSessionControllerTokens({
-              rootSecret: browserAuthorityRoot(deps),
+              rootSecret: authority,
               accountId: grant.accountId,
               workspaceId,
               browserSessionId,
@@ -1202,16 +2333,30 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               ...(origin ? { allowedOrigins: [origin] } : {}),
             });
             try {
-              await client.createSession({
-                browserSessionId,
-                controllerGeneration,
-                tokenGeneration: record.tokenGeneration,
-                ...tokens,
-                headed: !prepared.session.headless,
-                transport: placement.transport,
-                ...(linkedComputer ? { linkedComputer } : {}),
-                restore: restore!,
-              });
+              await withInteractionHolderHeartbeat(
+                deps,
+                {
+                  grant,
+                  workspaceId,
+                  sandboxGroupId: placement.controllerHostSandboxGroupId,
+                  holderId: interactionHolderId(browserSessionId),
+                  operationId: request.operationId,
+                  resourceId: browserSessionId,
+                  controllerGeneration,
+                },
+                async () =>
+                  await client.createSession({
+                    browserSessionId,
+                    controllerGeneration,
+                    tokenGeneration: record.tokenGeneration,
+                    ...tokens,
+                    headed: !prepared.session.headless,
+                    transport: browserRuntimeTransport(prepared.session, placement.transport),
+                    ...(linkedComputer ? { linkedComputer } : {}),
+                    ...(networkRoute ? { networkRoute } : {}),
+                    restore: restore!,
+                  }),
+              );
             } catch (error) {
               if (!isDefiniteBrowserControllerFailure(error)) throw error;
               try {
@@ -1243,7 +2388,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   grant,
                   workspaceId,
                   browserSessionId,
-                  prepared.session.placement,
+                  placement.controllerHostSandboxGroupId,
                 ).catch(() => undefined);
               }
               return failed;
@@ -1262,7 +2407,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             });
           },
         );
-        return context.json(BrowserSessionMutationResponse.parse(response), 200);
+        const parsed = BrowserSessionMutationResponse.parse(response);
+        observeLifecycleResult(deps.observability, startedAtMs, parsed);
+        return context.json(parsed, 200);
       } catch (error) {
         throw browserRouteError(error);
       } finally {
@@ -1279,6 +2426,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
       const browserSessionId = requireUuidParam(context, "browserSessionId");
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
+      const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
@@ -1302,10 +2450,12 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               grant,
               workspaceId,
               browserSessionId,
-              before.session.placement,
+              before.controllerHostSandboxGroupId,
             ).catch(() => undefined);
           }
-          return context.json(BrowserSessionMutationResponse.parse(prepared), 200);
+          const parsed = BrowserSessionMutationResponse.parse(prepared);
+          observeLifecycleResult(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
 
         const record = await getBrowserSessionControlRecord(deps.db, {
@@ -1328,9 +2478,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             grant,
             workspaceId,
             browserSessionId,
-            record.session.placement,
+            record.controllerHostSandboxGroupId,
           ).catch(() => undefined);
-          return context.json(BrowserSessionMutationResponse.parse(completed), 200);
+          const parsed = BrowserSessionMutationResponse.parse(completed);
+          observeLifecycleResult(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
         const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
         const response = await withBrowserPlacement(
@@ -1350,12 +2502,25 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             });
             const client = await provisionController(deps, grant, record, placement, origin);
             try {
-              await client.endSession(
+              await withInteractionHolderHeartbeat(
+                deps,
                 {
-                  browserSessionId,
+                  grant,
+                  workspaceId,
+                  sandboxGroupId: placement.controllerHostSandboxGroupId,
+                  holderId: interactionHolderId(browserSessionId),
+                  operationId: request.operationId,
+                  resourceId: browserSessionId,
                   controllerGeneration: binding.controllerGeneration,
                 },
-                { removeState: true },
+                async () =>
+                  await client.endSession(
+                    {
+                      browserSessionId,
+                      controllerGeneration: binding.controllerGeneration,
+                    },
+                    { removeState: true },
+                  ),
               );
             } catch (error) {
               // Physical absence already satisfies an exact end. A stale live
@@ -1376,12 +2541,14 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               grant,
               workspaceId,
               browserSessionId,
-              record.session.placement,
+              placement.controllerHostSandboxGroupId,
             ).catch(() => undefined);
             return completed;
           },
         );
-        return context.json(BrowserSessionMutationResponse.parse(response), 200);
+        const parsed = BrowserSessionMutationResponse.parse(response);
+        observeLifecycleResult(deps.observability, startedAtMs, parsed);
+        return context.json(parsed, 200);
       } catch (error) {
         throw browserRouteError(error);
       }
@@ -1442,6 +2609,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       waitSignal.throwIfAborted();
       return await callback({
         placement: expectedPlacement,
+        controllerHostSandboxGroupId: null,
         placementInstanceId: device.connectionGeneration,
         session: built.session as unknown as BrowserControlPlacementSession,
         lease: null,
@@ -1454,7 +2622,14 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         },
       });
     }
-    return await withChannelA(
+    const runWithChannelA =
+      operation === "browser.read" ||
+      operation === "browser.action" ||
+      operation === "browser.control" ||
+      operation === "browser.attach"
+        ? withChannelARead
+        : withChannelA;
+    return await runWithChannelA(
       channelServices,
       {
         accountId: grant.accountId,
@@ -1463,6 +2638,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         subjectId: grant.subjectId,
         waitSignal,
         operation,
+        retryControllerTransport: operation === "browser.read" || operation === "browser.action",
       },
       async (handle) => {
         if (expectedPlacement?.kind === "sandbox_group") {
@@ -1475,6 +2651,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           assertPlacementInstance(expectedPlacementInstanceId, handle.lease.instanceId);
           return await callback({
             placement: expectedPlacement,
+            controllerHostSandboxGroupId: expectedPlacement.sandboxGroupId,
             placementInstanceId: handle.lease.instanceId,
             session: handle.homeSession,
             lease: handle.lease,
@@ -1482,6 +2659,23 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           });
         }
 
+        if (expectedPlacement?.kind === "external_provider") {
+          if (!handle.lease?.instanceId) {
+            throw new BrowserSessionStateError(
+              "Remote BrowserSession controller placement is unavailable",
+            );
+          }
+          assertPlacementInstance(expectedPlacementInstanceId, handle.lease.instanceId);
+          return await callback({
+            placement: expectedPlacement,
+            controllerHostSandboxGroupId: sourceSession.sandboxGroupId,
+            placementInstanceId: handle.lease.instanceId,
+            session: handle.homeSession,
+            lease: handle.lease,
+            transport: externalBrowserTransport(deps, expectedPlacement),
+          });
+        }
+
         const resolved = await handle.routingSession.prime();
         if (expectedPlacement?.kind === "connected_machine") {
           if (
@@ -1496,18 +2690,13 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           assertPlacementInstance(expectedPlacementInstanceId, placementInstanceId);
           return await callback({
             placement: expectedPlacement,
+            controllerHostSandboxGroupId: null,
             placementInstanceId,
             session: resolved.session as unknown as BrowserControlPlacementSession,
             lease: null,
             transport: { kind: "managed" },
           });
         }
-        if (expectedPlacement) {
-          throw new BrowserControlUnsupportedError(
-            `browser placement ${expectedPlacement.kind} is not executable yet`,
-          );
-        }
-
         if (resolved.sandboxId === null) {
           if (!handle.lease?.instanceId) {
             throw new BrowserSessionStateError("BrowserSession home placement is unavailable");
@@ -1523,6 +2712,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               kind: "sandbox_group",
               sandboxGroupId: sourceSession.sandboxGroupId,
             },
+            controllerHostSandboxGroupId: sourceSession.sandboxGroupId,
             placementInstanceId: handle.lease.instanceId,
             session: handle.homeSession,
             lease: handle.lease,
@@ -1536,6 +2726,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           };
           return await callback({
             placement,
+            controllerHostSandboxGroupId: null,
             placementInstanceId: resolved.providerInstanceId ?? resolved.sandboxId,
             session: resolved.session as unknown as BrowserControlPlacementSession,
             lease: null,
@@ -1566,6 +2757,110 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     };
   }
 
+  function controllerOnlySession(url: string): BrowserControlPlacementSession {
+    const endpoint = exposedPortEndpointFromUrl(url);
+    return {
+      resolveExposedPort: async (port: number) => {
+        if (port !== BROWSER_CONTROL_PORT) {
+          throw new BrowserControlUnsupportedError(`cached controller cannot expose port ${port}`);
+        }
+        return endpoint;
+      },
+    };
+  }
+
+  async function cachedBrowserPlacement(
+    record: BrowserSessionControlRecord,
+  ): Promise<BrowserPlacement | null> {
+    const binding = record.session.controller;
+    const sandboxGroupId = record.controllerHostSandboxGroupId;
+    if (!binding || !sandboxGroupId) return null;
+    const lease = await readLease(deps.db, record.session.workspaceId, sandboxGroupId);
+    if (
+      !lease ||
+      (lease.liveness !== "warm" && lease.liveness !== "draining") ||
+      lease.instanceId !== binding.placementInstanceId ||
+      !lease.controllerDataPlaneUrl
+    ) {
+      return null;
+    }
+    return {
+      placement: record.session.placement,
+      controllerHostSandboxGroupId: sandboxGroupId,
+      placementInstanceId: binding.placementInstanceId,
+      session: controllerOnlySession(lease.controllerDataPlaneUrl),
+      lease,
+      transport:
+        record.session.placement.kind === "external_provider"
+          ? externalBrowserTransport(deps, record.session.placement)
+          : { kind: "managed" },
+    };
+  }
+
+  async function cacheBrowserControllerPlacement(
+    grant: AccessGrant,
+    workspaceId: string,
+    placement: BrowserPlacement,
+  ): Promise<BrowserPlacement> {
+    const sandboxGroupId = placement.controllerHostSandboxGroupId;
+    if (!sandboxGroupId || !placement.lease?.instanceId || !placement.session.resolveExposedPort) {
+      return placement;
+    }
+    const endpoint = await placement.session.resolveExposedPort(BROWSER_CONTROL_PORT);
+    const url = buildStreamUrl(endpoint);
+    const lease = await recordLeaseControllerDataPlaneUrl(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sandboxGroupId,
+      expectedEpoch: placement.lease.leaseEpoch,
+      expectedInstanceId: placement.lease.instanceId,
+      controllerDataPlaneUrl: url,
+    });
+    if (!lease) return placement;
+    return { ...placement, session: controllerOnlySession(url), lease };
+  }
+
+  async function withBrowserCreationController<T>(
+    routeDeps: ApiRouteDeps,
+    grant: AccessGrant,
+    workspaceId: string,
+    placement: BrowserPlacement,
+    adminToken: string,
+    origin: string | null,
+    operation: (client: BrowserControlClient) => Promise<T>,
+  ): Promise<T> {
+    const sandboxGroupId = placement.controllerHostSandboxGroupId;
+    const cachedUrl = placement.lease?.controllerDataPlaneUrl;
+    return await withCachedController({
+      cachedUrl: sandboxGroupId ? (cachedUrl ?? null) : null,
+      createCachedClient: (url) =>
+        new BrowserControlClient(controllerOnlySession(url), { adminToken }),
+      prepareCachedClient: async (client) => {
+        if (origin) await client.addAllowedOrigins([origin]);
+      },
+      invalidateCachedUrl: async () => {
+        if (!sandboxGroupId || !placement.lease) return;
+        await recordLeaseControllerDataPlaneUrl(routeDeps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sandboxGroupId,
+          expectedEpoch: placement.lease.leaseEpoch,
+          expectedInstanceId: placement.placementInstanceId,
+          controllerDataPlaneUrl: null,
+        });
+      },
+      provisionClient: async () => {
+        const { client } = await provisionBrowserControlClient(placement.session, {
+          adminToken,
+          nativeAuthority: nativeBrowserControllerAuthority(workspaceId, placement),
+          ...(origin ? { allowedOrigins: [origin] } : {}),
+        });
+        return client;
+      },
+      use: operation,
+    });
+  }
+
   async function withActiveBrowserController<T>(
     context: Context,
     grant: AccessGrant,
@@ -1580,6 +2875,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       binding: NonNullable<BrowserSessionControlRecord["session"]["controller"]>;
       placement: BrowserPlacement;
     }) => Promise<T>,
+    recoverMissing = true,
   ): Promise<T> {
     try {
       const record = await getBrowserSessionControlRecord(deps.db, {
@@ -1601,6 +2897,76 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       if (!admitted) {
         throw new BrowserSessionStateError("BrowserSession controller authority changed");
       }
+      const run = async (placement: BrowserPlacement): 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 tokens = deriveBrowserSessionControllerTokens({
+          rootSecret: browserAuthorityRoot(deps),
+          accountId: grant.accountId,
+          workspaceId,
+          placement: record.session.placement,
+          placementInstanceId: placement.placementInstanceId,
+          browserSessionId,
+          controllerGeneration: binding.controllerGeneration,
+          tokenGeneration: record.tokenGeneration,
+        });
+        const controller = {
+          client,
+          sessionClient: client.sessionClient({
+            reference: {
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+            },
+            ...tokens,
+          }),
+          record,
+          binding,
+          placement,
+        };
+        let result: T;
+        try {
+          result = await callback(controller);
+        } catch (error) {
+          if (!recoverMissing || !isMissingBrowserControllerSession(error)) throw error;
+          await recoverActiveBrowserController(
+            deps,
+            grant,
+            record,
+            binding,
+            placement,
+            client,
+            tokens,
+          );
+          result = await callback(controller);
+        }
+        return result;
+      };
+      const cached = await cachedBrowserPlacement(record);
+      if (cached) {
+        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))
+          ) {
+            throw error;
+          }
+          await recordLeaseControllerDataPlaneUrl(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            sandboxGroupId: cached.controllerHostSandboxGroupId!,
+            expectedEpoch: cached.lease!.leaseEpoch,
+            expectedInstanceId: cached.placementInstanceId,
+            controllerDataPlaneUrl: null,
+          }).catch(() => null);
+        }
+      }
+
       const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
       return await withBrowserPlacement(
         sourceSession,
@@ -1609,51 +2975,60 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         binding.placementInstanceId,
         channelOperation,
         context.req.raw.signal,
-        async (placement) => {
-          const client = await provisionController(
-            deps,
-            grant,
-            record,
-            placement,
-            requestOrigin(context, deps.settings.corsAllowOriginRegex),
-          );
-          const tokens = deriveBrowserSessionControllerTokens({
-            rootSecret: browserAuthorityRoot(deps),
-            accountId: grant.accountId,
-            workspaceId,
-            placement: record.session.placement,
-            placementInstanceId: placement.placementInstanceId,
-            browserSessionId,
-            controllerGeneration: binding.controllerGeneration,
-            tokenGeneration: record.tokenGeneration,
-          });
-          const result = await callback({
-            client,
-            sessionClient: client.sessionClient({
-              reference: {
-                browserSessionId,
-                controllerGeneration: binding.controllerGeneration,
-              },
-              ...tokens,
-            }),
-            record,
-            binding,
-            placement,
-          });
-          await touchBrowserSessionController(deps.db, {
-            accountId: grant.accountId,
-            workspaceId,
-            browserSessionId,
-            controllerGeneration: binding.controllerGeneration,
-          }).catch(() => false);
-          return result;
-        },
+        async (placement) =>
+          await run(
+            await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
+              () => placement,
+            ),
+          ),
       );
     } catch (error) {
       throw browserRouteError(error);
     }
   }
 
+  async function recoverActiveBrowserController(
+    routeDeps: ApiRouteDeps,
+    grant: AccessGrant,
+    record: BrowserSessionControlRecord,
+    binding: NonNullable<BrowserSessionControlRecord["session"]["controller"]>,
+    placement: BrowserPlacement,
+    client: BrowserControlClient,
+    tokens: ReturnType<typeof deriveBrowserSessionControllerTokens>,
+  ): Promise<void> {
+    const linkedComputer = await requireLinkedComputerBinding(
+      routeDeps,
+      grant,
+      record.session,
+      placement,
+    );
+    const networkRoute = await resolveActiveBrowserNetworkRouteLaunch({
+      deps: routeDeps,
+      grant,
+      record,
+      placement: placement.placement,
+    });
+    try {
+      await client.createSession({
+        browserSessionId: record.session.id,
+        controllerGeneration: binding.controllerGeneration,
+        tokenGeneration: record.tokenGeneration,
+        ...tokens,
+        headed: !record.session.headless,
+        transport: browserRuntimeTransport(record.session, placement.transport),
+        ...(linkedComputer ? { linkedComputer } : {}),
+        ...(networkRoute ? { networkRoute } : {}),
+      });
+    } catch (error) {
+      console.error("browser controller recovery failed", {
+        browserSessionId: record.session.id,
+        controllerGeneration: binding.controllerGeneration,
+        failure: interactionFailure(error),
+      });
+      throw error;
+    }
+  }
+
   async function finishSuspendedBrowserControllerCleanup(
     context: Context,
     grant: AccessGrant,
@@ -1701,7 +3076,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       grant,
       workspaceId,
       browserSessionId,
-      record.session.placement,
+      record.controllerHostSandboxGroupId,
     );
   }
 }
@@ -1713,6 +3088,13 @@ function browserCreateInput(
   placement: InteractionPlacement,
 ) {
   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") {
+    throw new BrowserControlUnsupportedError(
+      "Lightpanda is currently available only in managed agent sandboxes",
+    );
+  }
   return {
     accountId: grant.accountId,
     workspaceId,
@@ -1722,18 +3104,89 @@ function browserCreateInput(
     name: request.name ?? "Browser",
     initialUrl: request.initialUrl ?? null,
     placement,
-    driverId: BROWSER_DRIVER_ID,
-    engine: attached ? ("chrome" as const) : ("chromium" as const),
+    driverId:
+      engine === "lightpanda"
+        ? LIGHTPANDA_DRIVER_ID
+        : external
+          ? EXTERNAL_BROWSER_DRIVER_ID
+          : BROWSER_DRIVER_ID,
+    engine,
     headless: attached ? false : request.headless,
     identityId: request.identityId ?? null,
     baseRevisionId: request.baseRevisionId ?? null,
+    networkRouteId: request.networkRouteId ?? null,
     linkedComputerSessionId: request.linkedComputerSessionId ?? null,
     resolveDefaultRevision:
-      !attached && request.identityId !== undefined && request.baseRevisionId === undefined,
-    ...(attached ? { capabilities: ATTACHED_BROWSER_SESSION_CAPABILITIES } : {}),
+      !attached &&
+      !external &&
+      request.identityId !== undefined &&
+      request.baseRevisionId === undefined,
+    ...(attached
+      ? { capabilities: ATTACHED_BROWSER_SESSION_CAPABILITIES }
+      : external
+        ? { capabilities: EXTERNAL_BROWSER_SESSION_CAPABILITIES }
+        : engine === "lightpanda"
+          ? { capabilities: LIGHTPANDA_BROWSER_SESSION_CAPABILITIES }
+          : {}),
+  };
+}
+
+function browserRuntimeTransport(
+  session: BrowserSessionValue,
+  transport: PlacementBrowserTransport,
+): PlacementBrowserTransport {
+  if (transport.kind !== "managed") return transport;
+  return {
+    kind: "managed",
+    engine: session.engine === "lightpanda" ? "lightpanda" : "chromium",
   };
 }
 
+function externalBrowserTransport(
+  deps: ApiRouteDeps,
+  placement: Extract<InteractionPlacement, { kind: "external_provider" }>,
+): PlacementBrowserTransport {
+  if (placement.placementId !== "default") {
+    throw new BrowserControlUnsupportedError(
+      "only the configured default external browser placement is available",
+    );
+  }
+  if (placement.providerId === "browserbase") {
+    if (!deps.settings.browserbaseApiKey) {
+      throw new HTTPException(503, {
+        message: "Browserbase browser placement is not configured",
+      });
+    }
+    return {
+      kind: "external_provider",
+      providerId: "browserbase",
+      placementId: placement.placementId,
+      authority: { apiKey: deps.settings.browserbaseApiKey },
+    };
+  }
+  if (placement.providerId === "kernel") {
+    if (!deps.settings.kernelApiKey) {
+      throw new HTTPException(503, {
+        message: "Kernel browser placement is not configured",
+      });
+    }
+    return {
+      kind: "external_provider",
+      providerId: "kernel",
+      placementId: placement.placementId,
+      authority: {
+        apiKey: deps.settings.kernelApiKey,
+        ...(deps.settings.kernelEndpoint ? { endpoint: deps.settings.kernelEndpoint } : {}),
+      },
+      timeoutSeconds: deps.settings.kernelBrowserTimeoutSeconds,
+      stealth: deps.settings.kernelBrowserStealth,
+    };
+  }
+  throw new BrowserControlUnsupportedError(
+    `external browser provider ${placement.providerId} is not supported`,
+  );
+}
+
 function assertCreateReplay(
   request: CreateBrowserSessionRequestValue,
   session: BrowserSessionValue,
@@ -1743,11 +3196,27 @@ function assertCreateReplay(
       "BrowserSession create operation is bound to another placement",
     );
   }
+  const expectedEngine =
+    session.placement.kind === "attached_device"
+      ? "chrome"
+      : session.placement.kind === "external_provider"
+        ? "external"
+        : request.engine;
+  if (session.engine !== expectedEngine) {
+    throw new BrowserSessionOperationConflictError(
+      "BrowserSession create operation is bound to another browser engine",
+    );
+  }
   if ((request.identityId ?? null) !== session.identityId) {
     throw new BrowserSessionOperationConflictError(
       "BrowserSession create operation is bound to another identity",
     );
   }
+  if ((request.networkRouteId ?? null) !== session.networkRouteId) {
+    throw new BrowserSessionOperationConflictError(
+      "BrowserSession create operation is bound to another network route",
+    );
+  }
   if (request.baseRevisionId !== undefined && request.baseRevisionId !== session.baseRevisionId) {
     throw new BrowserSessionOperationConflictError(
       "BrowserSession create operation is bound to another revision",
@@ -1926,6 +3395,7 @@ async function prepareBrowserArtifactRestore(
   try {
     const signed = await objectStorage.createGetUrl({
       key: artifact.objectKey,
+      audience: signedUrlAudienceForPlacement(placement),
     });
     return {
       objectKey: artifact.objectKey,
@@ -1988,6 +3458,10 @@ function sameInteractionPlacement(
   }
 }
 
+function signedUrlAudienceForPlacement(placement: InteractionPlacement): "public" | "sandbox" {
+  return placement.kind === "sandbox_group" ? "sandbox" : "public";
+}
+
 async function ensureInteractionHolder(
   deps: ApiRouteDeps,
   grant: AccessGrant,
@@ -1996,14 +3470,14 @@ async function ensureInteractionHolder(
   placement: BrowserPlacement,
   waitSignal: AbortSignal,
 ): Promise<boolean> {
-  if (placement.placement.kind !== "sandbox_group") return false;
+  if (!placement.controllerHostSandboxGroupId) return false;
   if (!placement.lease?.instanceId) {
     throw new BrowserSessionStateError("BrowserSession lease placement is unavailable");
   }
   const acquired = await acquireLease(deps.db, {
     accountId: grant.accountId,
     workspaceId: sourceSession.workspaceId,
-    sandboxGroupId: placement.placement.sandboxGroupId,
+    sandboxGroupId: placement.controllerHostSandboxGroupId,
     kind: "interaction",
     holderId: interactionHolderId(browserSessionId),
     subjectId: sourceSession.id,
@@ -2028,7 +3502,7 @@ async function ensureInteractionHolder(
       grant,
       sourceSession.workspaceId,
       browserSessionId,
-      placement.placement,
+      placement.controllerHostSandboxGroupId,
     ).catch(() => undefined);
     throw new BrowserSessionStateError("BrowserSession placement fence changed; retry");
   }
@@ -2075,7 +3549,7 @@ async function ensureDispatchedGeneration(
     });
   }
   if (record.operation?.state !== "dispatched") {
-    throw new BrowserSessionStateError("BrowserSession create operation is not dispatchable");
+    throw new BrowserSessionStateError("BrowserSession operation is not dispatchable");
   }
   if (
     !record.session.controller ||
@@ -2119,6 +3593,24 @@ async function provisionController(
   ).client;
 }
 
+function connectController(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  record: BrowserSessionControlRecord,
+  placement: BrowserPlacement,
+): BrowserControlClient {
+  return new BrowserControlClient(placement.session, {
+    adminToken: deriveBrowserControllerAdminToken({
+      rootSecret: browserAuthorityRoot(deps),
+      accountId: grant.accountId,
+      workspaceId: record.session.workspaceId,
+      placement: record.session.placement,
+      placementInstanceId: placement.placementInstanceId,
+    }),
+    nativeAuthority: nativeBrowserControllerAuthority(record.session.workspaceId, placement),
+  });
+}
+
 function nativeBrowserControllerAuthority(
   workspaceId: string,
   placement: BrowserPlacement,
@@ -2146,13 +3638,13 @@ async function releaseInteractionHolder(
   grant: AccessGrant,
   workspaceId: string,
   browserSessionId: string,
-  placement: InteractionPlacement,
+  controllerHostSandboxGroupId: string | null,
 ): Promise<void> {
-  if (placement.kind !== "sandbox_group") return;
+  if (!controllerHostSandboxGroupId) return;
   await releaseLeaseHolder(deps.db, {
     accountId: grant.accountId,
     workspaceId,
-    sandboxGroupId: placement.sandboxGroupId,
+    sandboxGroupId: controllerHostSandboxGroupId,
     kind: "interaction",
     holderId: interactionHolderId(browserSessionId),
     idleGraceMs: deps.settings.sandboxIdleGraceMs,
@@ -2233,6 +3725,16 @@ function isDefiniteBrowserControllerFailure(error: unknown): boolean {
   );
 }
 
+function isMissingBrowserControllerSession(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" &&
+    ["browser session not found", "browser session is not active"].includes(error.error.message)
+  );
+}
+
 async function settleBrowserSessionSuspensionCaptureFailure(
   deps: ApiRouteDeps,
   input: {
@@ -2451,6 +3953,353 @@ function isTerminalOperation(state: string): boolean {
   return state === "completed" || state === "failed" || state === "outcome_unknown";
 }
 
+async function loadBoundBrowserCredential(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  workspaceId: string,
+  authority: Extract<SiteAuthAuthority, { kind: "connection_fields" }>,
+) {
+  return await loadExactInteractionCredential(deps, grant, workspaceId, authority.credential);
+}
+
+async function loadExactInteractionCredential(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  workspaceId: string,
+  reference: InteractionCredentialAuthorityRef,
+) {
+  const credential = await loadConnectionCredentialForBroker(deps.db, deps.settings, {
+    workspaceId,
+    connectionId: reference.connectionId,
+    providerDomain: reference.providerDomain,
+    subjectId: reference.connectionSubjectId,
+    allowSubjectOwned: reference.connectionSubjectId !== null,
+  });
+  if (
+    !credential ||
+    credential.id !== reference.connectionId ||
+    credential.accountId !== grant.accountId ||
+    credential.workspaceId !== workspaceId ||
+    credential.subjectId !== reference.connectionSubjectId ||
+    credential.providerDomain !== reference.providerDomain ||
+    credential.status !== "active"
+  ) {
+    throw new BrowserAuthCredentialError("Configured browser credential is unavailable");
+  }
+  return credential;
+}
+
+async function resolveBrowserNetworkRouteLaunch(input: {
+  deps: ApiRouteDeps;
+  grant: AccessGrant;
+  workspaceId: string;
+  browserSessionId: string;
+  operationId: string;
+  rootSecret: string;
+  placement: InteractionPlacement;
+}): Promise<PlacementBrowserNetworkRoute | null> {
+  const record = await getBrowserSessionControlRecord(input.deps.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    browserSessionId: input.browserSessionId,
+    operationId: input.operationId,
+  });
+  const route = record.networkRouteAuthority;
+  if (!route) return null;
+  const kind = route.configuration.kind;
+  const providerRoute =
+    kind === "managed"
+      ? managedNetworkRouteForPlacement(route.configuration, route.consistency, input.placement)
+      : undefined;
+  if (kind !== "managed" && input.placement.kind === "external_provider") {
+    throw new BrowserSessionStateError(
+      "External browser providers require a provider-managed NetworkRoute",
+    );
+  }
+  let proxyCredential: { username: string; password: string } | null = null;
+  let credentialVersion: number | null = null;
+  let proxyUrl: string | undefined;
+  const dispatched = record.operation?.state === "dispatched";
+  if (kind === "proxy") {
+    const reference = route.configuration.credential;
+    if (reference) {
+      try {
+        const credential = await loadExactInteractionCredential(
+          input.deps,
+          input.grant,
+          input.workspaceId,
+          reference,
+        );
+        credentialVersion = credential.version;
+        proxyCredential = proxyCredentialFromBundle(credential.credential);
+      } catch (error) {
+        if (route.authorityDigest && dispatched) {
+          return secretlessNetworkRouteReplay(route, kind, providerRoute);
+        }
+        throw error;
+      }
+      if (dispatched && route.credentialVersion !== credentialVersion) {
+        return secretlessNetworkRouteReplay(route, kind, providerRoute);
+      }
+    }
+    proxyUrl = browserProxyUrl(route.configuration, proxyCredential);
+  }
+  if (dispatched) {
+    if (!route.authorityDigest) {
+      throw new BrowserSessionStateError("BrowserSession route authority is not bound");
+    }
+    return {
+      routeId: route.routeId,
+      routeVersion: route.routeVersion,
+      authorityDigest: route.authorityDigest,
+      kind,
+      consistency: route.consistency,
+      ...(proxyUrl === undefined ? {} : { proxyUrl }),
+      ...(providerRoute === undefined ? {} : { providerRoute }),
+    };
+  }
+  const authorityDigest = deriveBrowserNetworkRouteAuthorityDigest({
+    rootSecret: input.rootSecret,
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    browserSessionId: input.browserSessionId,
+    routeId: route.routeId,
+    routeVersion: route.routeVersion,
+    credentialVersion,
+    configuration: route.configuration,
+    consistency: route.consistency,
+    proxyCredential,
+  });
+  const bound = await bindBrowserSessionNetworkRouteAuthority(input.deps.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    browserSessionId: input.browserSessionId,
+    operationId: input.operationId,
+    routeVersion: route.routeVersion,
+    credentialVersion,
+    authorityDigest,
+  });
+  if (bound.authorityDigest !== authorityDigest) {
+    throw new BrowserSessionOperationConflictError("BrowserSession route launch authority changed");
+  }
+  return {
+    routeId: route.routeId,
+    routeVersion: route.routeVersion,
+    authorityDigest,
+    kind,
+    consistency: route.consistency,
+    ...(proxyUrl === undefined ? {} : { proxyUrl }),
+    ...(providerRoute === undefined ? {} : { providerRoute }),
+  };
+}
+
+async function resolveActiveBrowserNetworkRouteLaunch(input: {
+  deps: ApiRouteDeps;
+  grant: AccessGrant;
+  record: BrowserSessionControlRecord;
+  placement: InteractionPlacement;
+}): Promise<PlacementBrowserNetworkRoute | null> {
+  const route = input.record.networkRouteAuthority;
+  if (!route) return null;
+  if (!route.authorityDigest) {
+    throw new BrowserSessionStateError("BrowserSession route authority is not bound");
+  }
+  const kind = route.configuration.kind;
+  const providerRoute =
+    kind === "managed"
+      ? managedNetworkRouteForPlacement(route.configuration, route.consistency, input.placement)
+      : undefined;
+  if (kind !== "managed" && input.placement.kind === "external_provider") {
+    throw new BrowserSessionStateError(
+      "External browser providers require a provider-managed NetworkRoute",
+    );
+  }
+  let proxyUrl: string | undefined;
+  if (kind === "proxy") {
+    const reference = route.configuration.credential;
+    let proxyCredential: { username: string; password: string } | null = null;
+    if (reference) {
+      const credential = await loadExactInteractionCredential(
+        input.deps,
+        input.grant,
+        input.record.session.workspaceId,
+        reference,
+      );
+      if (credential.version !== route.credentialVersion) {
+        throw new BrowserSessionStateError(
+          "BrowserSession proxy credential changed; resume the browser to reconnect safely",
+        );
+      }
+      proxyCredential = proxyCredentialFromBundle(credential.credential);
+    }
+    proxyUrl = browserProxyUrl(route.configuration, proxyCredential);
+  }
+  return {
+    routeId: route.routeId,
+    routeVersion: route.routeVersion,
+    authorityDigest: route.authorityDigest,
+    kind,
+    consistency: route.consistency,
+    ...(proxyUrl === undefined ? {} : { proxyUrl }),
+    ...(providerRoute === undefined ? {} : { providerRoute }),
+  };
+}
+
+function secretlessNetworkRouteReplay(
+  route: NonNullable<BrowserSessionControlRecord["networkRouteAuthority"]>,
+  kind: "direct" | "proxy" | "managed" | "tunnel",
+  providerRoute?: NonNullable<PlacementBrowserNetworkRoute["providerRoute"]>,
+): PlacementBrowserNetworkRoute {
+  if (!route.authorityDigest) {
+    throw new BrowserSessionStateError("BrowserSession route authority is not bound");
+  }
+  return {
+    routeId: route.routeId,
+    routeVersion: route.routeVersion,
+    authorityDigest: route.authorityDigest,
+    kind,
+    consistency: route.consistency,
+    ...(providerRoute === undefined ? {} : { providerRoute }),
+  };
+}
+
+function proxyCredentialFromBundle(credential: Readonly<Record<string, unknown>>): {
+  username: string;
+  password: string;
+} {
+  const username = credential.username;
+  const password = credential.password;
+  if (
+    typeof username !== "string" ||
+    Buffer.byteLength(username) < 1 ||
+    Buffer.byteLength(username) > 4_096 ||
+    username.includes("\0") ||
+    typeof password !== "string" ||
+    Buffer.byteLength(password) < 1 ||
+    Buffer.byteLength(password) > 16_384 ||
+    password.includes("\0")
+  ) {
+    throw new BrowserAuthCredentialError(
+      "Proxy credential must contain bounded username and password fields",
+    );
+  }
+  return { username, password };
+}
+
+function browserProxyUrl(
+  configuration: Extract<
+    NonNullable<BrowserSessionControlRecord["networkRouteAuthority"]>["configuration"],
+    { kind: "proxy" }
+  >,
+  credential: { username: string; password: string } | null,
+): string {
+  const rawHost = configuration.host;
+  if (
+    /[\s/@?#]/u.test(rawHost) ||
+    ((rawHost.includes("[") || rawHost.includes("]")) && !/^\[[^\]]+\]$/u.test(rawHost))
+  ) {
+    throw new BrowserSessionStateError("Network route proxy host is invalid");
+  }
+  const host = rawHost.includes(":") ? `[${rawHost.replace(/^\[|\]$/gu, "")}]` : rawHost;
+  let url: URL;
+  try {
+    url = new URL(`${configuration.protocol}://${host}:${configuration.port}`);
+  } catch {
+    throw new BrowserSessionStateError("Network route proxy host is invalid");
+  }
+  if (!url.hostname || url.pathname !== "/") {
+    throw new BrowserSessionStateError("Network route proxy host is invalid");
+  }
+  if (credential) {
+    url.username = credential.username;
+    url.password = credential.password;
+  }
+  return url.toString();
+}
+
+async function settleProtectedAuthReceipt(input: {
+  deps: ApiRouteDeps;
+  scope: {
+    accountId: string;
+    workspaceId: string;
+    actorSubjectId: string;
+    authRunId: string;
+  };
+  receipt: BrowserProtectedAuthFillReceiptValue;
+}) {
+  const { deps, scope, receipt } = input;
+  if (receipt.state === "completed") {
+    if (!receipt.observation) {
+      throw new BrowserControlProtocolError("protected-fill receipt omitted its observation");
+    }
+    return await completeProtectedAuthFill(deps.db, {
+      ...scope,
+      operationId: receipt.operationId,
+      status: receipt.observation.status,
+      targetGeneration: receipt.observation.target.targetGeneration,
+      documentGeneration: receipt.observation.target.documentGeneration,
+    });
+  }
+  if (receipt.state === "failed") {
+    if (!receipt.error) {
+      throw new BrowserControlProtocolError("protected-fill failure omitted its error");
+    }
+    const staleCodes = new Set([
+      "controller_stale",
+      "target_not_found",
+      "target_stale",
+      "observation_stale",
+      "document_stale",
+      "frame_stale",
+      "locator_not_found",
+      "locator_ambiguous",
+    ]);
+    return await completeProtectedAuthFill(deps.db, {
+      ...scope,
+      operationId: receipt.operationId,
+      status: staleCodes.has(receipt.error.code) ? "stale" : "failed",
+      failureCode: receipt.error.code,
+    });
+  }
+  if (receipt.state === "outcome_unknown") {
+    await markProtectedAuthFillOutcomeUnknown(deps.db, {
+      ...scope,
+      operationId: receipt.operationId,
+      errorCode: receipt.error?.code ?? "outcome_unknown",
+    });
+    throw new InteractionResourceStateError("Protected-fill outcome is unknown");
+  }
+  throw new InteractionResourceStateError(`Protected-fill operation is still ${receipt.state}`);
+}
+
+function assertAuthRunBrowser(actual: string, expected: string): void {
+  if (actual !== expected) {
+    throw new InteractionResourceConflictError("Auth run belongs to another browser session");
+  }
+}
+
+function browserUploadFileIds(action: BrowserActionRequestValue["action"]): string[] {
+  const actions = action.type === "batch" ? action.actions : [action];
+  return [
+    ...new Set(actions.flatMap((entry) => (entry.type === "upload" ? entry.workspaceFileIds : []))),
+  ];
+}
+
+function browserUploadFilename(value: string): string {
+  const normalized = value
+    .trim()
+    .replace(/[/\\]/gu, "_")
+    .replace(/[^A-Za-z0-9._ -]+/gu, "_")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, 240);
+  return normalized && normalized !== "." && normalized !== ".." ? normalized : "file";
+}
+
+function browserUploadSha256(value: string | null): string | null {
+  return value && /^[0-9a-f]{64}$/u.test(value) ? value : null;
+}
+
 function interactionFailure(error: unknown) {
   if (error instanceof BrowserControlRequestError) return error.error;
   if (
@@ -2480,6 +4329,89 @@ function interactionFailure(error: unknown) {
   };
 }
 
+function assertBrowserDownloadSaveSource(
+  current: BrowserDownloadValue,
+  expected: BrowserDownloadValue,
+): void {
+  if (
+    current.id !== expected.id ||
+    current.browserSessionId !== expected.browserSessionId ||
+    current.controllerGeneration !== expected.controllerGeneration ||
+    current.status !== "completed" ||
+    current.version !== expected.version ||
+    current.filename !== expected.filename ||
+    current.receivedBytes !== expected.receivedBytes ||
+    current.totalBytes !== expected.totalBytes ||
+    current.sha256 !== expected.sha256
+  ) {
+    throw new InteractionResourceStateError("Browser download changed before it was saved");
+  }
+}
+
+async function finalizeBrowserDownloadFile(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  workspaceId: string,
+  uploadId: string,
+): Promise<NonNullable<Awaited<ReturnType<typeof getFileUpload>>>> {
+  const objectStorage = deps.objectStorage;
+  if (!objectStorage) throw new HTTPException(503, { message: "object storage is not configured" });
+  let upload = await getFileUpload(deps.db, workspaceId, uploadId);
+  if (!upload) throw new InteractionResourceStateError("Browser download file upload is absent");
+  if (upload.status === "completed" && upload.file.status === "ready") {
+    await recordBrowserDownloadFileUsage(deps, grant, workspaceId, upload.file);
+    return upload;
+  }
+  if (upload.status !== "pending") {
+    throw new InteractionResourceStateError(
+      `Browser download file upload is ${upload.status.replace("_", " ")}`,
+    );
+  }
+  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" });
+  });
+  if (
+    Number(head.ContentLength ?? -1) !== upload.file.sizeBytes ||
+    (head.ContentType !== undefined && head.ContentType !== upload.file.contentType) ||
+    (upload.file.sha256 !== null && head.Metadata?.sha256 !== upload.file.sha256)
+  ) {
+    throw new HTTPException(502, { message: "browser download object failed verification" });
+  }
+  let file: FileAsset;
+  try {
+    file = await completeFileUpload(deps.db, workspaceId, upload.id);
+  } catch (error) {
+    const current = await getFileUpload(deps.db, workspaceId, upload.id);
+    if (current?.status !== "completed" || current.file.status !== "ready") throw error;
+    upload = current;
+    file = current.file;
+  }
+  await recordBrowserDownloadFileUsage(deps, grant, workspaceId, file);
+  return { ...upload, status: "completed", file };
+}
+
+async function recordBrowserDownloadFileUsage(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  workspaceId: string,
+  file: FileAsset,
+): Promise<void> {
+  await recordWorkspaceUsage(deps, {
+    accountId: grant.accountId,
+    workspaceId,
+    subjectId: grant.subjectId,
+    eventType: "file.uploaded",
+    quantity: file.sizeBytes,
+    unit: "byte",
+    sourceResourceType: "file",
+    sourceResourceId: file.id,
+    idempotencyKey: `file.uploaded:${workspaceId}:${file.id}`,
+  });
+}
+
 function browserRouteError(error: unknown): HTTPException {
   if (error instanceof HTTPException) return error;
   if (error instanceof BrowserSessionNotFoundError) {
@@ -2491,11 +4423,18 @@ function browserRouteError(error: unknown): HTTPException {
   if (error instanceof BrowserIdentityNotFoundError) {
     return new HTTPException(404, { message: error.message, cause: error });
   }
+  if (error instanceof InteractionResourceNotFoundError) {
+    return new HTTPException(404, { message: error.message, cause: error });
+  }
   if (
     error instanceof BrowserSessionOperationConflictError ||
     error instanceof BrowserSessionStateError ||
     error instanceof BrowserIdentityConflictError ||
-    error instanceof BrowserIdentityStateError
+    error instanceof BrowserIdentityStateError ||
+    error instanceof BrowserStateUploadStateError ||
+    error instanceof InteractionResourceConflictError ||
+    error instanceof InteractionResourceStateError ||
+    error instanceof BrowserAuthCredentialError
   ) {
     return new HTTPException(409, { message: error.message, cause: error });
   }