@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/browser-sessions.ts

@@ -1,11 +1,19 @@
+import { attachedBrowserViewer } from "../attached-browser-viewer";
+import {
+  assertEphemeralBrowserCreateEnabled,
+  ephemeralBrowserPartition,
+} from "../browser-ephemeral";
 import { randomUUID } from "node:crypto";
 import {
   environmentsEncryptionKeyBytes,
   resolveFirstPartyDelegationSecret,
   resolveStreamTokenSecret,
+  sandboxWarmRateMicrosPerSecond,
 } from "@opengeni/config";
 import {
   BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX,
+  EPHEMERAL_CHROMIUM_DRIVER_ID,
+  browserSessionStorageMode,
   BROWSER_CONTROL_WEBSOCKET_PROTOCOL,
   BROWSER_CONTROL_PORT,
   BROWSER_CONTROL_PROTOCOL_VERSION,
@@ -14,16 +22,18 @@ import {
   AttachedBrowserDevice,
   AttachedBrowserDeviceListResponse,
   BrowserActionCommand,
+  browserActionSecretTexts,
   BrowserActionRequest,
   BrowserDiagnosticKind,
   BrowserDownload,
   BrowserDownloadSaveRequest,
   BrowserDownloadSaveResponse,
   BrowserDownloadListResponse,
+  BrowserDomReadRequest,
+  BrowserDomReadResponse,
   BrowserExternalAuthCommand,
   BrowserOpenTargetRequest,
   BrowserObservation,
-  BrowserProtectedAuthFillCommand,
   BrowserSessionAttachment,
   BrowserSessionAttachmentRequest,
   BrowserSessionHeartbeatResponse,
@@ -31,21 +41,19 @@ import {
   BrowserSessionListResponse,
   BrowserSessionMutationResponse,
   BrowserTargetListResponse,
+  BrowserTargetState,
   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,
@@ -56,7 +64,6 @@ import {
   type BrowserRevisionMaterialization as BrowserRevisionMaterializationValue,
   type Session,
   type SessionAuthorizationOperation,
-  type SiteAuthAuthority,
 } from "@opengeni/contracts";
 import {
   getSessionAuthorityEpoch,
@@ -75,21 +82,23 @@ import {
   BrowserSessionNotFoundError,
   BrowserSessionOperationConflictError,
   BrowserSessionStateError,
+  SandboxPaidComputeAdmissionError,
   completeBrowserSessionEnd,
   completeExternalAuth,
   completeBrowserDownloadSave,
   completeFileUpload,
-  completeProtectedAuthFill,
   commitBrowserSessionSuspension,
   commitBrowserRevisionPublication,
   dispatchBrowserRevisionPublication,
   dispatchBrowserDownloadSave,
   dispatchBrowserSessionOperation,
   dispatchExternalAuth,
-  dispatchProtectedAuthFill,
   failBrowserSessionOperation,
+  failPreparedBrowserSessionEnd,
+  failPreparedBrowserSessionSuspend,
   failBrowserSessionResume,
   failBrowserSessionResumePreparation,
+  getExpiredBrowserSessionResume,
   failBrowserSessionSuspension,
   failBrowserRevisionPublication,
   findBrowserSessionControlRecordByOperation,
@@ -106,8 +115,6 @@ import {
   getFileUpload,
   getAuthRun,
   getExternalAuthPreparation,
-  getProtectedAuthFillPreparation,
-  getSiteAuthConnection,
   getSession,
   InteractionResourceConflictError,
   InteractionResourceNotFoundError,
@@ -115,20 +122,22 @@ import {
   listAuthRuns,
   listBrowserSessions,
   listAttachedBrowserDevices,
+  interactionControllerGone,
   prepareBrowserSessionCreate,
+  markEphemeralBrowserSessionLost,
   prepareExternalAuth,
   prepareBrowserDownloadSave,
   prepareBrowserSessionEnd,
   prepareBrowserSessionResume,
+  settleExpiredBrowserSessionResume,
+  continueExpiredBrowserSessionResume,
   prepareBrowserSessionSuspend,
   prepareBrowserRevisionPublication,
-  prepareProtectedAuthFill,
   reportAuthRun,
   releaseLeaseHolder,
   readLease,
   recordLeaseControllerDataPlaneUrl,
   loadConnectionCredentialForBroker,
-  markProtectedAuthFillOutcomeUnknown,
   startAuthRun,
   touchBrowserSessionController,
   verifyAuthRun,
@@ -169,6 +178,8 @@ import {
   provisionBrowserControlClient,
   renewSandboxProviderExpiration,
   type BrowserControlPlacementSession,
+  type BrowserControlScreenshotOptions,
+  type BrowserControlFrame,
   type PlacementBrowserStateCaptureReceipt,
   type PlacementBrowserNetworkRoute,
   type PlacementBrowserTransport,
@@ -189,9 +200,14 @@ import {
   controllerCacheAllowsHostFetch,
   controllerCachedUrlIsUsable,
   shouldPersistControllerDataPlaneUrl,
+  isRetryableControllerTransport,
   withCachedController,
+  withControllerTransportRecovery,
 } from "../controller-data-plane";
-import { filterInteractionSessionsForGrant } from "../interaction-agent-access";
+import {
+  filterInteractionSessionsForGrant,
+  parseInteractionSessionListQuery,
+} from "../interaction-agent-access";
 import { withInteractionHolderHeartbeat } from "../interaction-holder-heartbeat";
 import {
   browserStateArtifactAad,
@@ -201,11 +217,13 @@ import {
   unwrapBrowserStateDataKey,
   wrapBrowserStateDataKey,
 } from "../browser-state-authority";
-import {
-  BrowserAuthCredentialError,
-  resolveProtectedAuthFieldValues,
-} from "../browser-auth-broker";
 import { managedNetworkRouteForPlacement } from "../browser-network-route";
+import {
+  endBrowserDiscardingLostRuntime,
+  endExpiredResumeSettingAsideInterruptedLaunch,
+} from "../browser-lost-runtime-end";
+import { resolveBrowserActionFences, type BrowserActionFences } from "../browser-action-fences";
+import { InteractionRouteStages, reportInteractionRouteStages } from "../interaction-route-stages";
 import { validateInteractionRequestOrigin } from "../http/cors";
 import { ApiHttpError } from "../http/api-error";
 import { interactionControlApiError } from "../http/interaction-control-error";
@@ -221,6 +239,15 @@ import {
 } from "../interaction-metrics";
 import { withChannelA, withChannelARead, type ChannelAOperation } from "../sandbox/channel-a";
 import { sanitizeFilename } from "./files";
+import { USER_CONTENT_SECURITY_HEADERS } from "../http/user-content";
+import { wrongInteractionPlacementMessage } from "./interaction-placement-message";
+import {
+  releaseBrowserPasskeys,
+  resolveInteractionSecretValues,
+  syncBrowserPasskeys,
+  type InteractionSecretsPort,
+} from "../interaction-secrets";
+import { requirePlacementAcceptsSecretValues } from "../interaction-agent-version";
 
 const BROWSER_DRIVER_ID = "opengeni.cdp.v1";
 const LIGHTPANDA_DRIVER_ID = "opengeni.lightpanda.cdp.v1";
@@ -237,7 +264,12 @@ type BrowserPlacement = {
   transport: PlacementBrowserTransport;
 };
 
-export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
+export function registerBrowserSessionRoutes(
+  app: Hono,
+  deps: ApiRouteDeps,
+  options: { interactionSecrets?: InteractionSecretsPort | null } = {},
+): void {
+  const interactionSecrets = options.interactionSecrets ?? null;
   const channelServices = {
     db: deps.db,
     settings: deps.settings,
@@ -252,8 +284,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     return context.json(
       AttachedBrowserDeviceListResponse.parse(
         await listAttachedBrowserDevices(deps.db, {
-          accountId: grant.accountId,
-          workspaceId,
+          ...(await attachedBrowserViewer(deps, grant, workspaceId)),
           includeDisconnected,
         }),
       ),
@@ -268,8 +299,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       return context.json(
         AttachedBrowserDevice.parse(
           await getAttachedBrowserDevice(deps.db, {
-            accountId: grant.accountId,
-            workspaceId,
+            ...(await attachedBrowserViewer(deps, grant, workspaceId)),
             deviceId,
           }),
         ),
@@ -288,6 +318,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     const listed = await listBrowserSessions(deps.db, {
       accountId: grant.accountId,
       workspaceId,
+      ...parseInteractionSessionListQuery(context.req.query()),
     });
     return context.json(
       BrowserSessionListResponse.parse({
@@ -319,11 +350,18 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
     const request = await parseJsonBody(context, CreateBrowserSessionRequest);
     const startedAtMs = performance.now();
+    const stages = new InteractionRouteStages("create");
     await authorizeSourceSession(deps, grant, request.sessionId, "session.control");
+    stages.mark("authorize");
     const origin = requestOrigin(context, deps.settings);
     const authority = browserAuthorityRoot(deps);
+    let prepared: Awaited<ReturnType<typeof prepareBrowserSessionCreate>> | null = null;
 
     try {
+      assertEphemeralBrowserCreateEnabled(
+        request,
+        deps.settings.experimentalBrowserContextPoolEnabled,
+      );
       const existing = await findBrowserSessionControlRecordByOperation(deps.db, {
         accountId: grant.accountId,
         workspaceId,
@@ -335,7 +373,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         );
       }
       if (existing) assertCreateReplay(request, existing.session);
-      let prepared = existing
+      stages.mark("replay_check");
+      prepared = existing
         ? await prepareBrowserSessionCreate(
             deps.db,
             browserCreateInput(grant, workspaceId, request, existing.session.placement),
@@ -362,6 +401,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       }
 
       const sourceSession = await requireSourceSession(deps, workspaceId, request.sessionId);
+      stages.mark("source_session");
       const response = await withBrowserPlacement(
         sourceSession,
         grant,
@@ -370,6 +410,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         "browser.create",
         context.req.raw.signal,
         async (placement) => {
+          stages.mark("placement_resolve");
           let revisionAuthority: BrowserRevisionArtifactAuthority | null = null;
           if (!prepared) {
             prepared = await prepareBrowserSessionCreate(
@@ -377,6 +418,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               browserCreateInput(grant, workspaceId, request, placement.placement),
             );
           }
+          stages.mark("prepare");
           if (isTerminalOperation(prepared.operation.state)) return prepared;
 
           if (prepared.session.baseRevisionId && !revisionAuthority) {
@@ -397,6 +439,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             placement.placement,
             revisionAuthority,
           );
+          stages.mark("restore");
 
           try {
             const networkRoute = await resolveBrowserNetworkRouteLaunch({
@@ -408,6 +451,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               rootSecret: authority,
               placement: placement.placement,
             });
+            stages.mark("network_route");
             const interactionHeld = await ensureInteractionHolder(
               deps,
               grant,
@@ -416,6 +460,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               placement,
               context.req.raw.signal,
             );
+            stages.mark("holder");
             const record = await ensureDispatchedGeneration(
               deps,
               grant,
@@ -435,6 +480,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               }
               throw error;
             });
+            stages.mark("generation");
             const preparedSession = prepared.session;
             const controllerGeneration = requireOperationGeneration(record);
             const adminToken = deriveBrowserControllerAdminToken({
@@ -482,18 +528,25 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                       controllerGeneration,
                     },
                     async () => {
+                      stages.mark("provision");
                       await ensureHeadedBrowserDisplayStack(
                         placement.session,
                         preparedSession.headless,
                         linkedComputer !== null,
                       );
+                      stages.mark("display");
                       return await client.createSession({
                         browserSessionId: preparedSession.id,
                         controllerGeneration,
                         tokenGeneration: record.tokenGeneration,
                         ...tokens,
                         headed: !preparedSession.headless,
-                        transport: browserRuntimeTransport(preparedSession, placement.transport),
+                        transport: browserRuntimeTransport(
+                          preparedSession,
+                          placement.transport,
+                          placement.placementInstanceId,
+                          authority,
+                        ),
                         ...(linkedComputer ? { linkedComputer } : {}),
                         ...(networkRoute ? { networkRoute } : {}),
                         ...(request.initialUrl ? { initialUrl: request.initialUrl } : {}),
@@ -503,9 +556,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   );
                 },
               );
+              stages.mark("launch");
               await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
                 () => placement,
               );
+              stages.mark("placement_cache_write");
             } catch (error) {
               if (
                 error instanceof BrowserControlTransportError ||
@@ -538,7 +593,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             // Once the controller has accepted the exact binding, a persistence
             // failure is retried against that same idempotent physical session.
             // Never terminalize or release its placement authority here.
-            return await activateBrowserSession(deps.db, {
+            const activated = await activateBrowserSession(deps.db, {
               accountId: grant.accountId,
               workspaceId,
               operationId: request.operationId,
@@ -550,6 +605,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               },
               engineVersion: null,
             });
+            stages.mark("activate");
+            return activated;
           } finally {
             restore?.dataKey.fill(0);
             restore?.aad.fill(0);
@@ -558,11 +615,24 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       );
       const parsed = BrowserSessionMutationResponse.parse(response);
       observeLifecycleResult(deps.observability, startedAtMs, parsed);
+      reportInteractionRouteStages(context, deps.observability, stages);
       return context.json(
         parsed,
         parsed.operation.state === "completed" && !parsed.operation.replayed ? 201 : 200,
       );
     } catch (error) {
+      if (prepared) {
+        // The operation lock fences a concurrent dispatch. Once a controller
+        // binding exists, retain its exact receipt for physical reconciliation.
+        await failBrowserSessionOperation(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          operationId: request.operationId,
+          browserSessionId: prepared.session.id,
+          onlyIfPreparedCreate: true,
+          error: interactionFailure(error),
+        }).catch(() => undefined);
+      }
       throw browserRouteError(error);
     }
   });
@@ -614,6 +684,28 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     },
   );
 
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/open-with-inventory",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:control",
+      );
+      const request = await parseJsonBody(context, BrowserOpenTargetRequest);
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.control",
+        "browser.control",
+        async ({ sessionClient }) =>
+          BrowserTargetListResponse.parse(await sessionClient.openTargetWithInventory(request.url)),
+      );
+      return context.json(result, 201);
+    },
+  );
+
   app.post(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/select",
     async (context) => {
@@ -889,6 +981,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             workspaceId,
             session: sourceSession,
             subjectId: grant.subjectId,
+            grant,
             waitSignal: context.req.raw.signal,
             operation: "browser.download.save",
           },
@@ -898,6 +991,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               destinationPath: save.destinationPath,
               overwrite: save.overwrite,
               mayReplaceExisting: save.overwrite && dispatched.dispatchedNow,
+              // Missing folders on the relative destination are created; the
+              // import still confines every existing ancestor to the workspace.
+              createParents: true,
               sizeBytes: save.download.receivedBytes,
               sha256: save.download.sha256!,
               source: {
@@ -934,11 +1030,13 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
   app.get(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/observation",
     async (context) => {
+      const stages = new InteractionRouteStages("observe");
       const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
         context,
         "sessions:read",
       );
       const targetId = requireOpaqueParam(context, "targetId");
+      stages.mark("auth");
       const result = await withActiveBrowserController(
         context,
         grant,
@@ -946,15 +1044,114 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         browserSessionId,
         "session.read",
         "browser.read",
-        async ({ sessionClient }) => await sessionClient.observe(targetId),
+        async ({ sessionClient }) => {
+          stages.mark("placement");
+          try {
+            return await sessionClient.observe(targetId);
+          } finally {
+            stages.mark("dispatch");
+          }
+        },
+        true,
+        stages,
       );
+      reportInteractionRouteStages(context, deps.observability, stages);
       return context.json(result);
     },
   );
 
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/state",
+    async (context) => {
+      const stages = new InteractionRouteStages("target_state");
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      stages.mark("auth");
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => {
+          stages.mark("placement");
+          try {
+            return await sessionClient.targetState(targetId);
+          } finally {
+            stages.mark("dispatch");
+          }
+        },
+        true,
+        stages,
+      );
+      reportInteractionRouteStages(context, deps.observability, stages);
+      return context.json(BrowserTargetState.parse(result));
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/dom-read",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const request = await parseJsonBody(context, BrowserDomReadRequest);
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.readDom(targetId, request),
+      );
+      return context.json(BrowserDomReadResponse.parse(result));
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/screenshot",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const captureOptions = parseBrowserScreenshotOptions(new URL(context.req.url).searchParams);
+      const frame = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient, record }) => {
+          if (!record.session.capabilities.screenshots) {
+            throw new BrowserControlUnsupportedError(
+              "This browser engine does not render page screenshots; use semantic observation",
+            );
+          }
+          try {
+            return await sessionClient.capture(targetId, captureOptions);
+          } catch (error) {
+            throw browserScreenshotError(error);
+          }
+        },
+      );
+      return browserScreenshotResponse(frame);
+    },
+  );
+
   app.post(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/actions",
     async (context) => {
+      const stages = new InteractionRouteStages("act");
       const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
         context,
         "sessions:control",
@@ -964,7 +1161,12 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       if (workspaceFileIds.length > 0) {
         await requireAccessGrant(context, deps, workspaceId, "files:read");
       }
+      stages.mark("auth");
       const startedAtMs = performance.now();
+      // Omitted fences mean the target's current state. Read them once from the
+      // live controller in this request (a recovery retry of the callback must
+      // replay the same command digest, so it reuses the first read).
+      let resolvedFences: BrowserActionFences | null = null;
       const result = await withActiveBrowserController(
         context,
         grant,
@@ -973,19 +1175,38 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         "session.control",
         "browser.action",
         async ({ sessionClient, binding, record, sourceAuthorization }) => {
-          const command = BrowserActionCommand.parse({
+          stages.mark("placement");
+          const passkeySync = (refresh: boolean) =>
+            syncBrowserPasskeys({
+              port: interactionSecrets,
+              grant,
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+              client: sessionClient,
+              refresh,
+              log: (event, fields) => console.warn(event, { browserSessionId, ...fields }),
+            });
+          // Before the action this browser takes over the principal's passkeys.
+          // It is independent of the fence read, so both run together; the
+          // action is dispatched only after the takeover settles.
+          const passkeyTakeover = passkeySync(true);
+          resolvedFences ??= await resolveBrowserActionFences(request, () =>
+            sessionClient.targetState(request.targetId),
+          );
+          stages.mark("fences");
+          const commandFields = {
             protocolVersion: BROWSER_CONTROL_PROTOCOL_VERSION,
             operationId: request.operationId,
             browserSessionId,
             controllerGeneration: binding.controllerGeneration,
             targetId: request.targetId,
-            expectedTargetGeneration: request.expectedTargetGeneration,
-            expectedDocumentGeneration: request.expectedDocumentGeneration,
-            expectedFrameId: request.expectedFrameId,
+            ...resolvedFences,
             actor: interactionActorForGrant(grant),
             observationMode: request.observationMode,
             action: request.action,
-          });
+          };
+          // Validate the public command before resolving any reference.
+          BrowserActionCommand.parse(commandFields);
           if (workspaceFileIds.length > 0) {
             let alreadyAdmitted = false;
             try {
@@ -1034,10 +1255,46 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               });
             }
           }
-          return await sessionClient.action(command);
+          await passkeyTakeover;
+          stages.mark("passkey_pre");
+          // Resolved last, right before dispatch, so TOTP codes are fresh (Q-33).
+          const secretValues = await resolveInteractionSecretValues({
+            port: interactionSecrets,
+            grant,
+            texts: browserActionSecretTexts(request.action),
+            use: {
+              surface: "browser",
+              toolName: "browser_act",
+              operationId: request.operationId,
+            },
+            beforeResolve: requirePlacementAcceptsSecretValues(
+              deps.db,
+              grant,
+              workspaceId,
+              record.session.placement,
+            ),
+          });
+          stages.mark("secrets");
+          try {
+            return await sessionClient.action(
+              BrowserActionCommand.parse({
+                ...commandFields,
+                ...(secretValues === undefined ? {} : { secretValues }),
+              }),
+            );
+          } finally {
+            stages.mark("dispatch");
+            // Write back what the action did (new registrations, sign counts)
+            // without holding the response: unacknowledged events stay in
+            // browserd, and the session's next sync waits for this one.
+            void passkeySync(false);
+          }
         },
+        true,
+        stages,
       );
       observeBrowserActionResult(deps.observability, startedAtMs, request, result);
+      reportInteractionRouteStages(context, deps.observability, stages);
       return context.json(result);
     },
   );
@@ -1200,209 +1457,6 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     },
   );
 
-  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) => {
@@ -1749,7 +1803,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             browserSessionId,
             controllerGeneration: binding.controllerGeneration,
           };
-          await client.createViewGrant(reference, {
+          const viewGrant = await client.createViewGrant(reference, {
             grantId,
             token,
             expiresAt,
@@ -1841,6 +1895,10 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             controllerGeneration: binding.controllerGeneration,
             targetId: request.targetId,
             stream,
+            ...(viewGrant.fencedInputBatches === true ? { fencedInputBatches: true } : {}),
+            ...(viewGrant.focusedInputObservations === true
+              ? { focusedInputObservations: true }
+              : {}),
             expiresAt,
           });
         },
@@ -2047,6 +2105,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
       const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings);
+      let preparedForDispatch = false;
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2098,6 +2157,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           return context.json(parsed, 200);
         }
 
+        preparedForDispatch = true;
+
         const record = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
           workspaceId,
@@ -2259,10 +2320,19 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         observeLifecycleResult(deps.observability, startedAtMs, parsed);
         return context.json(parsed, 200);
       } catch (error) {
-        throw browserRouteError(error);
-      }
-    },
-  );
+        if (preparedForDispatch) {
+          await failPreparedBrowserSessionSuspend(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+            operationId: request.operationId,
+            error: interactionFailure(error),
+          });
+        }
+        throw browserRouteError(error);
+      }
+    },
+  );
 
   app.post(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/resume",
@@ -2281,6 +2351,34 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           browserSessionId,
         });
         await authorizeSourceSession(deps, grant, before.sourceSessionId, "session.control");
+        if (
+          before.session.lifecycle === "lost" &&
+          before.session.failureCode === "controller_transition_expired"
+        ) {
+          // A resume whose transition expired never activated. When its
+          // controller still holds that generation's working copy, continue the
+          // same browser from it; nothing is restored over it or discarded.
+          const continued = await continueExpiredBrowserResume(
+            context,
+            grant,
+            workspaceId,
+            browserSessionId,
+            request.operationId,
+          );
+          if (continued) {
+            const parsed = BrowserSessionMutationResponse.parse(continued);
+            observeLifecycleResult(deps.observability, startedAtMs, parsed);
+            return context.json(parsed, 200);
+          }
+          // Otherwise end its retained controller generation, then resume
+          // normally from the same durable state.
+          await settleExpiredBrowserResume(context, grant, workspaceId, browserSessionId);
+          before = await getBrowserSessionControlRecord(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+          });
+        }
         if (before.session.lifecycle === "suspended" && before.session.controller) {
           await finishSuspendedBrowserControllerCleanup(
             context,
@@ -2522,6 +2620,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
       const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings);
+      let endPreparation: {
+        restoreLifecycle: BrowserSessionValue["lifecycle"];
+        restoreFailureCode: string | null;
+        expectedControllerGeneration: string | null;
+      } | null = null;
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2536,6 +2639,9 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           browserSessionId,
           operationId: request.operationId,
           actorSubjectId: grant.subjectId,
+          expectedLifecycle: before.session.lifecycle,
+          expectedFailureCode: before.session.failureCode,
+          expectedControllerGeneration: before.session.controller?.controllerGeneration ?? null,
         });
         if (isTerminalOperation(prepared.operation.state)) {
           if (prepared.operation.state === "completed") {
@@ -2546,11 +2652,19 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               browserSessionId,
               before.controllerHostSandboxGroupId,
             ).catch(() => undefined);
+            await releaseBrowserPasskeys(interactionSecrets, browserSessionId);
           }
           const parsed = BrowserSessionMutationResponse.parse(prepared);
           observeLifecycleResult(deps.observability, startedAtMs, parsed);
           return context.json(parsed, 200);
         }
+        if (before.session.lifecycle !== "ending") {
+          endPreparation = {
+            restoreLifecycle: before.session.lifecycle,
+            restoreFailureCode: before.session.failureCode,
+            expectedControllerGeneration: before.session.controller?.controllerGeneration ?? null,
+          };
+        }
 
         const record = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2559,13 +2673,19 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           operationId: request.operationId,
         });
         const binding = record.session.controller;
-        if (!binding) {
+        // A browser with no controller, or whose controller can never be
+        // reached again, ends here: nothing physical remains to clean up, and
+        // completing under the bound generation fences that controller off.
+        if (
+          !binding ||
+          (await browserControllerGone(grant, workspaceId, record.session.placement))
+        ) {
           const completed = await completeBrowserSessionEnd(deps.db, {
             accountId: grant.accountId,
             workspaceId,
             operationId: request.operationId,
             browserSessionId,
-            expectedControllerGeneration: null,
+            expectedControllerGeneration: binding?.controllerGeneration ?? null,
           });
           await releaseInteractionHolder(
             deps,
@@ -2574,6 +2694,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             browserSessionId,
             record.controllerHostSandboxGroupId,
           ).catch(() => undefined);
+          await releaseBrowserPasskeys(interactionSecrets, browserSessionId);
           const parsed = BrowserSessionMutationResponse.parse(completed);
           observeLifecycleResult(deps.observability, startedAtMs, parsed);
           return context.json(parsed, 200);
@@ -2608,13 +2729,10 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
                   controllerGeneration: binding.controllerGeneration,
                 },
                 async () =>
-                  await client.endSession(
-                    {
-                      browserSessionId,
-                      controllerGeneration: binding.controllerGeneration,
-                    },
-                    { removeState: true },
-                  ),
+                  await endBrowserDiscardingLostRuntime(client, {
+                    browserSessionId,
+                    controllerGeneration: binding.controllerGeneration,
+                  }),
               );
             } catch (error) {
               // Physical absence already satisfies an exact end. A stale live
@@ -2637,6 +2755,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
               browserSessionId,
               placement.controllerHostSandboxGroupId,
             ).catch(() => undefined);
+            await releaseBrowserPasskeys(interactionSecrets, browserSessionId);
             return completed;
           },
         );
@@ -2644,6 +2763,16 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         observeLifecycleResult(deps.observability, startedAtMs, parsed);
         return context.json(parsed, 200);
       } catch (error) {
+        if (endPreparation) {
+          await failPreparedBrowserSessionEnd(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+            operationId: request.operationId,
+            ...endPreparation,
+            error: interactionFailure(error),
+          });
+        }
         throw browserRouteError(error);
       }
     },
@@ -2657,26 +2786,27 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     operation: ChannelAOperation,
     waitSignal: AbortSignal,
     callback: (placement: BrowserPlacement) => Promise<T>,
+    allowOperationReplay = true,
   ): Promise<T> {
     if (expectedPlacement?.kind === "attached_device") {
       waitSignal.throwIfAborted();
+      // Personal machines are controlled only for their owner, as everywhere else.
+      const viewer = await attachedBrowserViewer(deps, grant, sourceSession.workspaceId);
       const device = await getAttachedBrowserDevice(deps.db, {
-        accountId: grant.accountId,
-        workspaceId: sourceSession.workspaceId,
+        ...viewer,
         deviceId: expectedPlacement.deviceId,
       });
       if (device.state !== "connected") {
+        recordAttachedBrowserUnavailable(deps.observability, "disconnected");
         throw new BrowserSessionStateError("Attached browser is disconnected");
       }
-      const enrollment = await getLiveEnrollmentConnection(
-        deps.db,
-        sourceSession.workspaceId,
-        device.enrollmentId,
-      );
+      const enrollment = await getLiveEnrollmentConnection(deps.db, viewer, device.enrollmentId);
       if (!enrollment || enrollment.status !== "active" || !enrollment.connectionInstanceId) {
+        recordAttachedBrowserUnavailable(deps.observability, "machine_unavailable");
         throw new BrowserSessionStateError("Attached browser machine is unavailable");
       }
       if (!enrollment.workspaceRoot) {
+        recordAttachedBrowserUnavailable(deps.observability, "no_workspace_root");
         throw new BrowserSessionStateError(
           "Attached browser machine has not reported an absolute workspace root",
         );
@@ -2746,9 +2876,16 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         workspaceId: sourceSession.workspaceId,
         session: sourceSession,
         subjectId: grant.subjectId,
+        grant,
         waitSignal,
         operation,
         retryControllerTransport: operation === "browser.read" || operation === "browser.action",
+        allowOperationReplay,
+        ...(expectedPlacementInstanceId &&
+        (expectedPlacement?.kind === "sandbox_group" ||
+          expectedPlacement?.kind === "external_provider")
+          ? { retainedInstanceId: expectedPlacementInstanceId }
+          : {}),
       },
       async (handle) => {
         if (expectedPlacement?.kind === "sandbox_group") {
@@ -2792,6 +2929,11 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             resolved.kind !== "selfhosted" ||
             resolved.sandboxId !== expectedPlacement.sandboxId
           ) {
+            if (operation === "browser.create") {
+              throw new HTTPException(422, {
+                message: wrongInteractionPlacementMessage(expectedPlacement.sandboxId),
+              });
+            }
             return await throwBrowserSourcePlacementChanged(
               grant,
               sourceSession.id,
@@ -3024,6 +3166,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       sourceAuthorization: ResolvedSessionAuthorization | null;
     }) => Promise<T>,
     recoverMissing = true,
+    stages?: InteractionRouteStages,
   ): Promise<T> {
     try {
       const record = await getBrowserSessionControlRecord(deps.db, {
@@ -3031,12 +3174,14 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         workspaceId,
         browserSessionId,
       });
+      stages?.mark("record");
       const sourceAuthorization = await authorizeSourceSession(
         deps,
         grant,
         record.sourceSessionId,
         authorizationOperation,
       );
+      stages?.mark("authorize");
       let sourceSession: Session | null = null;
       if (record.session.placement?.kind === "connected_machine") {
         sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
@@ -3048,6 +3193,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           );
         }
       }
+      stages?.mark("source_session");
       if (record.session.lifecycle !== "active" || !record.session.controller) {
         throw new BrowserSessionStateError("BrowserSession is not active");
       }
@@ -3061,10 +3207,19 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       if (!admitted) {
         throw new BrowserSessionStateError("BrowserSession controller authority changed");
       }
-      const run = async (placement: BrowserPlacement): Promise<T> => {
+      stages?.mark("control");
+      const safelyReplayable =
+        browserSessionStorageMode(record.session) !== "ephemeral_context" &&
+        (channelOperation === "browser.read" || channelOperation === "browser.action");
+      let controllerTransportFailed = false;
+      const controllerRecoveryState = { attempted: false };
+      const run = async (
+        placement: BrowserPlacement,
+        provisionedClient?: BrowserControlClient,
+      ): Promise<T> => {
         // An active binding already proves browserd was provisioned. Reusing
         // it avoids restarting/checking the sidecar on every live input.
-        const client = connectController(deps, grant, record, placement);
+        const client = provisionedClient ?? connectController(deps, grant, record, placement);
         const tokens = deriveBrowserSessionControllerTokens({
           rootSecret: browserAuthorityRoot(deps),
           accountId: grant.accountId,
@@ -3093,6 +3248,30 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         try {
           result = await callback(controller);
         } catch (error) {
+          if (
+            browserSessionStorageMode(record.session) === "ephemeral_context" &&
+            (isMissingBrowserControllerSession(error) ||
+              (error instanceof BrowserControlRequestError &&
+                error.error.code === "controller_lost"))
+          ) {
+            const retired = await markEphemeralBrowserSessionLost(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+            });
+            if (retired)
+              await releaseInteractionHolder(
+                deps,
+                grant,
+                workspaceId,
+                browserSessionId,
+                record.controllerHostSandboxGroupId,
+              );
+            throw new BrowserSessionStateError(
+              "Ephemeral browser context was lost; create a new BrowserSession. No identity or operation was replayed.",
+            );
+          }
           if (!recoverMissing || !isMissingBrowserControllerSession(error)) throw error;
           await recoverActiveBrowserController(
             deps,
@@ -3102,25 +3281,22 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             placement,
             client,
             tokens,
+            authorizationOperation,
           );
           result = await callback(controller);
         }
         return result;
       };
       const cached = await cachedBrowserPlacement(record);
+      stages?.mark("placement_cache");
       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))
-          ) {
+          if (!safelyReplayable || !isRetryableControllerTransport(error)) {
             throw error;
           }
+          controllerTransportFailed = true;
           await recordLeaseControllerDataPlaneUrl(deps.db, {
             accountId: grant.accountId,
             workspaceId,
@@ -3140,12 +3316,54 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         binding.placementInstanceId,
         channelOperation,
         context.req.raw.signal,
-        async (placement) =>
-          await run(
-            await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
-              () => placement,
-            ),
-          ),
+        async (placement) => {
+          stages?.mark("placement_resolve");
+          const use = async () => {
+            const cachedPlacement = await cacheBrowserControllerPlacement(
+              grant,
+              workspaceId,
+              placement,
+            ).catch(() => placement);
+            stages?.mark("placement_cache_write");
+            return await run(cachedPlacement);
+          };
+          if (browserSessionStorageMode(record.session) === "ephemeral_context") return await use();
+          return await withControllerTransportRecovery({
+            channelOperation,
+            placementKind: placement.placement.kind,
+            recoveryState: controllerRecoveryState,
+            transportAlreadyFailed: controllerTransportFailed,
+            use,
+            admitRecovery: async () => {
+              if (
+                !(await touchBrowserSessionController(deps.db, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  browserSessionId,
+                  controllerGeneration: binding.controllerGeneration,
+                }))
+              ) {
+                throw new BrowserSessionStateError("BrowserSession controller authority changed");
+              }
+            },
+            recover: async () => {
+              // Provision and restore through the original exec-capable session;
+              // the cached tunnel alone cannot start browserd or its display.
+              const client = await provisionController(
+                deps,
+                grant,
+                record,
+                placement,
+                requestOrigin(context, deps.settings),
+              );
+              await cacheBrowserControllerPlacement(grant, workspaceId, placement).catch(
+                () => placement,
+              );
+              return await run(placement, client);
+            },
+          });
+        },
+        browserSessionStorageMode(record.session) !== "ephemeral_context",
       );
     } catch (error) {
       throw browserRouteError(error);
@@ -3171,6 +3389,23 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     );
   }
 
+  /** See `interactionControllerGone`: a removed machine or a disconnected
+   * Chrome device; a managed browser on a machine that is only offline waits. */
+  async function browserControllerGone(
+    grant: AccessGrant,
+    workspaceId: string,
+    placement: InteractionPlacement | null,
+  ): Promise<boolean> {
+    if (placement?.kind !== "connected_machine" && placement?.kind !== "attached_device") {
+      return false;
+    }
+    return await interactionControllerGone(
+      deps.db,
+      await attachedBrowserViewer(deps, grant, workspaceId),
+      placement,
+    );
+  }
+
   async function recoverActiveBrowserController(
     routeDeps: ApiRouteDeps,
     grant: AccessGrant,
@@ -3179,7 +3414,66 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     placement: BrowserPlacement,
     client: BrowserControlClient,
     tokens: ReturnType<typeof deriveBrowserSessionControllerTokens>,
+    authorizationOperation: SessionAuthorizationOperation,
   ): Promise<void> {
+    if (browserSessionStorageMode(record.session) === "ephemeral_context") {
+      throw new BrowserSessionStateError(
+        "Ephemeral browser context was lost; create a new BrowserSession. Its identity and operations cannot be restored or replayed.",
+      );
+    }
+    const transport = browserRuntimeTransport(record.session, placement.transport);
+    const recoverWorkingDirectory =
+      transport.kind === "managed" &&
+      transport.engine === "chromium" &&
+      !transport.ephemeralPartition &&
+      browserSessionStorageMode(record.session) === "private_profile";
+    if (recoverWorkingDirectory) {
+      // Missing controller memory cannot admit a stale source, token, placement
+      // or route snapshot. Reuse the existing durable authority before recovery.
+      await authorizeSourceSession(
+        routeDeps,
+        grant,
+        record.sourceSessionId,
+        authorizationOperation,
+      );
+      const current = await getBrowserSessionControlRecord(routeDeps.db, {
+        accountId: grant.accountId,
+        workspaceId: record.session.workspaceId,
+        browserSessionId: record.session.id,
+      });
+      if (
+        current.sourceSessionId !== record.sourceSessionId ||
+        current.session.lifecycle !== "active" ||
+        current.session.controller?.controllerGeneration !== binding.controllerGeneration ||
+        current.session.controller.placementInstanceId !== placement.placementInstanceId ||
+        current.session.controller.controllerId !== binding.controllerId ||
+        current.tokenGeneration !== record.tokenGeneration ||
+        !sameInteractionPlacement(current.session.placement, record.session.placement) ||
+        current.session.driverId !== record.session.driverId ||
+        current.session.engine !== record.session.engine ||
+        current.session.headless !== record.session.headless ||
+        current.session.linkedComputerSessionId !== record.session.linkedComputerSessionId ||
+        current.session.networkRouteId !== record.session.networkRouteId ||
+        JSON.stringify(current.networkRouteAuthority) !==
+          JSON.stringify(record.networkRouteAuthority)
+      ) {
+        throw new BrowserSessionStateError("BrowserSession controller authority changed");
+      }
+      if (record.session.placement.kind === "connected_machine") {
+        const source = await requireSourceSession(
+          routeDeps,
+          record.session.workspaceId,
+          record.sourceSessionId,
+        );
+        if (source.activeSandboxId !== record.session.placement.sandboxId) {
+          return await throwBrowserSourcePlacementChanged(
+            grant,
+            record.sourceSessionId,
+            record.session.placement.sandboxId,
+          );
+        }
+      }
+    }
     const linkedComputer = await ensureLinkedComputerController(
       routeDeps,
       grant,
@@ -3199,13 +3493,25 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         record.session.headless,
         linkedComputer !== null,
       );
+      if (
+        recoverWorkingDirectory &&
+        !(await touchBrowserSessionController(routeDeps.db, {
+          accountId: grant.accountId,
+          workspaceId: record.session.workspaceId,
+          browserSessionId: record.session.id,
+          controllerGeneration: binding.controllerGeneration,
+        }))
+      ) {
+        throw new BrowserSessionStateError("BrowserSession controller authority changed");
+      }
       await client.createSession({
         browserSessionId: record.session.id,
         controllerGeneration: binding.controllerGeneration,
         tokenGeneration: record.tokenGeneration,
         ...tokens,
         headed: !record.session.headless,
-        transport: browserRuntimeTransport(record.session, placement.transport),
+        transport,
+        ...(recoverWorkingDirectory ? { recoverExistingWorkingDirectory: true } : {}),
         ...(linkedComputer ? { linkedComputer } : {}),
         ...(networkRoute ? { networkRoute } : {}),
       });
@@ -3219,6 +3525,245 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     }
   }
 
+  /** Continue an expired resume on its retained controller generation when the
+   * controller still holds that generation's own working copy (a resident
+   * browser, or its preserved profile and launch receipt after the controller
+   * restarted). The controller's existing same-generation recovery adopts or
+   * relaunches it from that directory, so the record, its history and the
+   * possibly newer working profile all survive. Returns null when the browser
+   * cannot be continued this way, leaving the record unchanged for the
+   * settle-and-restore path. */
+  async function continueExpiredBrowserResume(
+    context: Context,
+    grant: AccessGrant,
+    workspaceId: string,
+    browserSessionId: string,
+    operationId: string,
+  ): Promise<BrowserSessionMutationResponse | null> {
+    const expired = await getExpiredBrowserSessionResume(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      browserSessionId,
+    });
+    if (!expired?.controllerGeneration) return null;
+    const record = await getBrowserSessionControlRecord(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      browserSessionId,
+    });
+    const binding = record.session.controller;
+    if (binding?.controllerGeneration !== expired.controllerGeneration) {
+      throw new BrowserSessionStateError("BrowserSession controller authority changed");
+    }
+    // Only a private profile has a working copy the controller can adopt.
+    if (browserSessionStorageMode(record.session) !== "private_profile") return null;
+    const rootSecret = browserAuthorityRoot(deps);
+    const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
+    if (
+      record.session.placement.kind === "connected_machine" &&
+      sourceSession.activeSandboxId !== record.session.placement.sandboxId
+    ) {
+      return null;
+    }
+    return await withBrowserPlacement(
+      sourceSession,
+      grant,
+      record.session.placement,
+      binding.placementInstanceId,
+      "browser.resume",
+      context.req.raw.signal,
+      async (placement) => {
+        const transport = browserRuntimeTransport(record.session, placement.transport);
+        if (
+          transport.kind !== "managed" ||
+          transport.engine !== "chromium" ||
+          transport.ephemeralPartition
+        ) {
+          return null;
+        }
+        const client = await provisionController(
+          deps,
+          grant,
+          record,
+          placement,
+          requestOrigin(context, deps.settings),
+        );
+        let linkedComputer: Awaited<ReturnType<typeof ensureLinkedComputerController>>;
+        try {
+          linkedComputer = await ensureLinkedComputerController(
+            deps,
+            grant,
+            record.session,
+            placement,
+            client,
+          );
+        } catch (error) {
+          // Its working copy was launched on a desktop that is gone.
+          if (error instanceof BrowserSessionStateError) return null;
+          throw error;
+        }
+        const networkRoute = await resolveActiveBrowserNetworkRouteLaunch({
+          deps,
+          grant,
+          record,
+          placement: placement.placement,
+        });
+        const tokens = deriveBrowserSessionControllerTokens({
+          rootSecret,
+          accountId: grant.accountId,
+          workspaceId,
+          browserSessionId,
+          placement: placement.placement,
+          placementInstanceId: placement.placementInstanceId,
+          controllerGeneration: binding.controllerGeneration,
+          tokenGeneration: record.tokenGeneration,
+        });
+        const interactionHeld = await ensureInteractionHolder(
+          deps,
+          grant,
+          sourceSession,
+          browserSessionId,
+          placement,
+          context.req.raw.signal,
+        );
+        const release = async () => {
+          if (!interactionHeld) return;
+          await releaseInteractionHolder(
+            deps,
+            grant,
+            workspaceId,
+            browserSessionId,
+            placement.controllerHostSandboxGroupId,
+          ).catch(() => undefined);
+        };
+        try {
+          await withInteractionHolderHeartbeat(
+            deps,
+            {
+              grant,
+              workspaceId,
+              sandboxGroupId: placement.controllerHostSandboxGroupId,
+              holderId: interactionHolderId(browserSessionId),
+              operationId,
+              // This operation is recorded only after the controller adopts
+              // the working copy; until then the expired resume holds authority.
+              continuesExpiredBrowserResume: true,
+              resourceId: browserSessionId,
+              controllerGeneration: binding.controllerGeneration,
+            },
+            async () => {
+              await ensureHeadedBrowserDisplayStack(
+                placement.session,
+                record.session.headless,
+                linkedComputer !== null,
+              );
+              await client.createSession({
+                browserSessionId,
+                controllerGeneration: binding.controllerGeneration,
+                tokenGeneration: record.tokenGeneration,
+                ...tokens,
+                headed: !record.session.headless,
+                transport,
+                recoverExistingWorkingDirectory: true,
+                ...(linkedComputer ? { linkedComputer } : {}),
+                ...(networkRoute ? { networkRoute } : {}),
+              });
+            },
+          );
+        } catch (error) {
+          // The controller proves no adoptable working copy for this generation
+          // (none was completed, or its authority or profile changed): leave
+          // the record for the settle-and-restore path.
+          if (
+            isDefiniteBrowserControllerFailure(error) &&
+            error instanceof BrowserControlRequestError &&
+            error.error.code === "resource_unavailable"
+          ) {
+            await release();
+            return null;
+          }
+          throw error;
+        }
+        return await continueExpiredBrowserSessionResume(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          browserSessionId,
+          operationId,
+          actorSubjectId: grant.subjectId,
+          controller: binding,
+        });
+      },
+    );
+  }
+
+  /** End the retained controller generation of an expired resume and return
+   * the browser to suspended. Other lost browsers are left unchanged so the
+   * normal resume preparation refuses them. */
+  async function settleExpiredBrowserResume(
+    context: Context,
+    grant: AccessGrant,
+    workspaceId: string,
+    browserSessionId: string,
+  ): Promise<void> {
+    const expired = await getExpiredBrowserSessionResume(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      browserSessionId,
+    });
+    if (!expired) return;
+    const record = await getBrowserSessionControlRecord(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      browserSessionId,
+    });
+    const binding = record.session.controller;
+    if ((binding?.controllerGeneration ?? null) !== expired.controllerGeneration) {
+      throw new BrowserSessionStateError("BrowserSession controller authority changed");
+    }
+    if (binding) {
+      browserAuthorityRoot(deps);
+      const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
+      await withBrowserPlacement(
+        sourceSession,
+        grant,
+        record.session.placement,
+        binding.placementInstanceId,
+        "browser.resume",
+        context.req.raw.signal,
+        async (placement) => {
+          const client = await provisionController(
+            deps,
+            grant,
+            record,
+            placement,
+            requestOrigin(context, deps.settings),
+          );
+          // A resident or provably never-completed launch is ended exactly; an
+          // interrupted launch whose profile no browser runs is set aside
+          // intact; a launch that completed (adoptable) or whose profile may
+          // be in use stays preserved and refuses this resume.
+          await endExpiredResumeSettingAsideInterruptedLaunch(client, {
+            browserSessionId,
+            controllerGeneration: binding.controllerGeneration,
+          });
+        },
+      );
+    }
+    await settleExpiredBrowserSessionResume(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      browserSessionId,
+      expectedControllerGeneration: expired.controllerGeneration,
+    });
+    await releaseInteractionHolder(
+      deps,
+      grant,
+      workspaceId,
+      browserSessionId,
+      record.controllerHostSandboxGroupId,
+    ).catch(() => undefined);
+  }
+
   async function finishSuspendedBrowserControllerCleanup(
     context: Context,
     grant: AccessGrant,
@@ -3286,18 +3831,27 @@ function sourcePlacementChangedApiError(interactionResource: "browser_session"):
   });
 }
 
-function browserCreateInput(
+export function browserCreateInput(
   grant: AccessGrant,
   workspaceId: string,
   request: CreateBrowserSessionRequestValue,
   placement: InteractionPlacement,
 ) {
+  if (request.storageMode === "ephemeral_context" && placement.kind !== "sandbox_group") {
+    throw new BrowserControlUnsupportedError(
+      "Ephemeral contexts require a managed sandbox placement",
+    );
+  }
   const attached = placement.kind === "attached_device";
   const external = placement.kind === "external_provider";
   const engine = attached ? ("chrome" as const) : external ? ("external" as const) : request.engine;
-  if (engine === "lightpanda" && placement.kind !== "sandbox_group") {
+  if (
+    request.engine === "lightpanda" &&
+    placement.kind !== "sandbox_group" &&
+    placement.kind !== "connected_machine"
+  ) {
     throw new BrowserControlUnsupportedError(
-      "Lightpanda is currently available only in managed agent sandboxes",
+      "Lightpanda requires a managed sandbox or Connected Machine browser placement",
     );
   }
   return {
@@ -3310,11 +3864,13 @@ function browserCreateInput(
     initialUrl: request.initialUrl ?? null,
     placement,
     driverId:
-      engine === "lightpanda"
-        ? LIGHTPANDA_DRIVER_ID
-        : external
-          ? EXTERNAL_BROWSER_DRIVER_ID
-          : BROWSER_DRIVER_ID,
+      request.storageMode === "ephemeral_context"
+        ? EPHEMERAL_CHROMIUM_DRIVER_ID
+        : engine === "lightpanda"
+          ? LIGHTPANDA_DRIVER_ID
+          : external
+            ? EXTERNAL_BROWSER_DRIVER_ID
+            : BROWSER_DRIVER_ID,
     engine,
     headless: attached ? false : request.headless,
     identityId: request.identityId ?? null,
@@ -3339,7 +3895,21 @@ function browserCreateInput(
 function browserRuntimeTransport(
   session: BrowserSessionValue,
   transport: PlacementBrowserTransport,
+  placementInstanceId?: string,
+  rootSecret?: string,
 ): PlacementBrowserTransport {
+  if (browserSessionStorageMode(session) === "ephemeral_context") {
+    if (transport.kind !== "managed" || !placementInstanceId || !rootSecret) {
+      throw new BrowserControlUnsupportedError(
+        "Ephemeral contexts cannot recover or change their placement",
+      );
+    }
+    return {
+      kind: "managed",
+      engine: "chromium",
+      ephemeralPartition: ephemeralBrowserPartition(session, placementInstanceId, rootSecret),
+    };
+  }
   if (transport.kind !== "managed") return transport;
   return {
     kind: "managed",
@@ -3401,6 +3971,11 @@ function assertCreateReplay(
       "BrowserSession create operation is bound to another placement",
     );
   }
+  if (request.storageMode !== browserSessionStorageMode(session)) {
+    throw new BrowserSessionOperationConflictError(
+      "BrowserSession create operation is bound to another storage mode",
+    );
+  }
   const expectedEngine =
     session.placement.kind === "attached_device"
       ? "chrome"
@@ -3739,7 +4314,9 @@ async function ensureInteractionHolder(
   if (!placement.lease?.instanceId) {
     throw new BrowserSessionStateError("BrowserSession lease placement is unavailable");
   }
-  const sandboxRuntime = await resolveSessionSandboxRuntime(deps.db, deps.settings, sourceSession);
+  const sandboxRuntime = await resolveSessionSandboxRuntime(deps.db, deps.settings, sourceSession, {
+    grant,
+  });
   const acquired = await acquireLease(deps.db, {
     accountId: grant.accountId,
     workspaceId: sourceSession.workspaceId,
@@ -3748,8 +4325,13 @@ async function ensureInteractionHolder(
     holderId: interactionHolderId(browserSessionId),
     subjectId: sourceSession.id,
     backend: placement.lease.backend,
+    warmBilling: {
+      mode: deps.settings.sandboxWarmBillingMode,
+      rateMicrosPerSecond: sandboxWarmRateMicrosPerSecond(deps.settings, placement.lease.backend),
+    },
     os: placement.lease.os,
     image: sandboxRuntime.image,
+    imagePolicy: "new_creates_only",
     rigVersionId: sourceSession.rigVersionId,
     leaseTtlMs: deps.settings.sandboxLeaseTtlMs,
     expectedEpoch: placement.lease.leaseEpoch,
@@ -4023,6 +4605,7 @@ async function settleBrowserSessionSuspensionCaptureFailure(
   return await failBrowserSessionSuspension(deps.db, {
     ...input,
     ...(outcomeUnknown ? { state: "outcome_unknown" as const } : {}),
+    missingControllerSession: error.status === 404 && isMissingBrowserControllerSession(error),
     error: error.error,
   });
 }
@@ -4160,6 +4743,86 @@ function optionalBoundedInteger(
   return parsed;
 }
 
+export function parseBrowserScreenshotOptions(
+  query: URLSearchParams,
+): BrowserControlScreenshotOptions {
+  for (const key of ["fullPage", "format", "quality"]) {
+    if (query.getAll(key).length > 1) {
+      throw new HTTPException(400, { message: `duplicate browser screenshot ${key}` });
+    }
+  }
+  const fullPage = query.get("fullPage");
+  if (fullPage !== null && fullPage !== "true" && fullPage !== "false") {
+    throw new HTTPException(400, { message: "invalid browser screenshot fullPage" });
+  }
+  const format = query.get("format");
+  if (format !== null && format !== "jpeg" && format !== "png") {
+    throw new HTTPException(400, { message: "invalid browser screenshot format" });
+  }
+  const quality = query.get("quality");
+  const parsedQuality = quality === null ? null : optionalBoundedInteger(quality, 1, 100);
+  if (quality !== null && parsedQuality === null) {
+    throw new HTTPException(400, { message: "invalid browser screenshot quality" });
+  }
+  return {
+    ...(fullPage === null ? {} : { fullPage: fullPage === "true" }),
+    ...(format === null ? {} : { format }),
+    ...(parsedQuality === null ? {} : { quality: parsedQuality }),
+  };
+}
+
+/** Preserve the controller's definite tab diagnosis (a tab that stopped
+ * answering, or one whose renderer crashed) through the public API with its
+ * own code and guidance. Any other controller failure keeps the ordinary
+ * envelope, which never publishes driver diagnostics. This only handles typed
+ * read/pre-dispatch failures. Dispatched action uncertainty stays in the
+ * action receipt, never relabeled as a safe retry. */
+export function browserTabDiagnosisError(error: unknown): unknown {
+  if (!(error instanceof BrowserControlRequestError)) return error;
+  const code = error.error.code;
+  if (code !== "tab_not_responding" && code !== "tab_crashed") return error;
+  const failure = new ApiHttpError(409, {
+    code,
+    message: error.error.message,
+    retryable: false,
+    outcomeUnknown: false,
+  });
+  failure.cause = error;
+  return failure;
+}
+
+/** Keep a definite read timeout useful without publishing driver diagnostics. */
+export function browserScreenshotError(error: unknown): unknown {
+  if (error instanceof BrowserControlRequestError && error.error.code === "timeout") {
+    const failure = new ApiHttpError(504, {
+      code: "upstream_unavailable",
+      message:
+        "This tab did not produce a screenshot in time. Other browser operations may still work.",
+      retryable: error.retryable,
+      outcomeUnknown: false,
+    });
+    failure.cause = error;
+    return failure;
+  }
+  return error;
+}
+
+export function browserScreenshotResponse(
+  frame: Pick<BrowserControlFrame, "data" | "mediaType" | "metadataHeader">,
+): Response {
+  // Node Buffers can be views into a larger backing allocation. Copy exactly
+  // the image bytes before constructing the Response.
+  return new Response(Uint8Array.from(frame.data).buffer, {
+    status: 200,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": frame.mediaType,
+      "x-opengeni-browser-frame": frame.metadataHeader,
+      ...USER_CONTENT_SECURITY_HEADERS,
+    },
+  });
+}
+
 function isUuid(value: unknown): value is string {
   return (
     typeof value === "string" &&
@@ -4214,13 +4877,9 @@ 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);
+/** A configured browser credential (proxy or provider authority) is unusable. */
+class BrowserAuthCredentialError extends Error {
+  override readonly name = "BrowserAuthCredentialError";
 }
 
 async function loadExactInteractionCredential(
@@ -4478,61 +5137,6 @@ function browserProxyUrl(
   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");
@@ -4712,10 +5316,30 @@ async function recordBrowserDownloadFileUsage(
   });
 }
 
+/** A user's own attached browser could not be reached for an operation. */
+function recordAttachedBrowserUnavailable(
+  observability: ApiRouteDeps["observability"],
+  reason: "disconnected" | "machine_unavailable" | "no_workspace_root",
+): void {
+  try {
+    observability?.incrementCounter({
+      name: "opengeni_attached_browser_unavailable_total",
+      help: "Browser operations refused because the user's attached browser (or its machine) was unreachable, by closed reason.",
+      labels: { reason },
+    });
+  } catch {
+    // Telemetry never changes the refusal.
+  }
+}
+
 function browserRouteError(error: unknown): HTTPException {
+  const tabDiagnosis = browserTabDiagnosisError(error);
+  if (tabDiagnosis instanceof ApiHttpError) return tabDiagnosis;
   const connectedMachineError = interactionControlApiError(error, "browser");
   if (connectedMachineError) return connectedMachineError;
   if (error instanceof HTTPException) return error;
+  if (error instanceof SandboxPaidComputeAdmissionError)
+    return new HTTPException(402, { message: error.message, cause: error });
   if (error instanceof BrowserSessionNotFoundError) {
     return new HTTPException(404, { message: error.message, cause: error });
   }