@opengeni/api-router 0.30.3 → 1.0.0

package/src/routes/computer-sessions.ts

@@ -1,15 +1,19 @@
 import { randomUUID } from "node:crypto";
-import { resolveFirstPartyDelegationSecret, resolveStreamTokenSecret } from "@opengeni/config";
+import {
+  resolveFirstPartyDelegationSecret,
+  resolveStreamTokenSecret,
+  sandboxWarmRateMicrosPerSecond,
+} from "@opengeni/config";
 import {
   BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX,
   BROWSER_CONTROL_PORT,
   COMPUTER_CONTROL_WEBSOCKET_PROTOCOL,
-  COMPUTER_RFB_WEBSOCKET_PROTOCOL,
   ComputerActionCommand,
   ComputerActionRequest,
   ComputerSessionAttachment,
   ComputerSessionAttachmentRequest,
   ComputerSessionHeartbeatResponse,
+  ComputerSessionInputPosture,
   ComputerSessionLifecycleRequest,
   ComputerSessionListResponse,
   ComputerSessionMutationResponse,
@@ -25,18 +29,21 @@ import {
   type SessionAuthorizationOperation,
 } from "@opengeni/contracts";
 import {
+  getSessionAuthorityEpoch,
   acquireLease,
   activateComputerSession,
   completeComputerSessionEnd,
   ComputerSessionNotFoundError,
   ComputerSessionOperationConflictError,
   ComputerSessionStateError,
+  SandboxPaidComputeAdmissionError,
   dispatchComputerSessionOperation,
   failComputerSessionOperation,
   findComputerSessionControlRecordByOperation,
   getAttachedBrowserDevice,
   getComputerSessionControlRecord,
-  getEnrollment,
+  getLiveEnrollmentConnection,
+  getSandbox,
   getSession,
   listComputerSessions,
   prepareComputerSessionCreate,
@@ -44,14 +51,17 @@ import {
   releaseLeaseHolder,
   readLease,
   recordLeaseControllerDataPlaneUrl,
+  terminalizeStaleConnectedInteractionPlacement,
   touchComputerSessionController,
   type ComputerSessionControlRecord,
   type LeaseSnapshot,
 } from "@opengeni/db";
 import {
+  hasPermission,
   requireAccessGrant,
   requireSessionAuthorization,
   relayConfigFromSettings,
+  resolveSessionSandboxRuntime,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   type ApiRouteDeps,
@@ -64,6 +74,7 @@ import {
   BrowserControlServerUnsupportedError,
   BrowserControlTransportError,
   BrowserControlUnsupportedError,
+  ComputerFrameEvidenceMismatchError,
   buildSelfhostedBackendSession,
   buildStreamUrl,
   exposedPortEndpointFromUrl,
@@ -71,7 +82,11 @@ import {
   NatsControlRpc,
   NatsOpStreamTransport,
   provisionBrowserControlClient,
+  validateComputerControlFrameEvidence,
+  renewSandboxProviderExpiration,
   type BrowserControlPlacementSession,
+  type ComputerControlFrame,
+  type ExpectedComputerFrameEvidence,
 } from "@opengeni/runtime/sandbox";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -81,19 +96,109 @@ import {
   deriveComputerSessionControllerTokens,
   deriveComputerViewGrantToken,
 } from "../browser-controller-authority";
-import { withCachedController } from "../controller-data-plane";
+import { connectedMachineComputerAccessError } from "../connected-machine-computer-access";
+import {
+  controllerCacheAllowsHostFetch,
+  controllerCachedUrlIsUsable,
+  shouldPersistControllerDataPlaneUrl,
+  withCachedController,
+} from "../controller-data-plane";
+import { filterInteractionSessionsForGrant } from "../interaction-agent-access";
 import { withInteractionHolderHeartbeat } from "../interaction-holder-heartbeat";
-import { allowedCorsOrigin } from "../http/cors";
-import { observeComputerActionResult, observeLifecycleResult } from "../interaction-metrics";
+import { validateInteractionRequestOrigin } from "../http/cors";
+import { ApiHttpError } from "../http/api-error";
+import { interactionControlApiError } from "../http/interaction-control-error";
+import {
+  createInteractionFrameProxyAttachment,
+  placementUsesInteractionFrameProxy,
+} from "../interaction-frame-proxy";
+import {
+  observeComputerActionResult,
+  observeComputerFrameEvidenceMismatch,
+  observeLifecycleResult,
+} from "../interaction-metrics";
 import { withChannelA, withChannelARead, type ChannelAOperation } from "../sandbox/channel-a";
+import { USER_CONTENT_SECURITY_HEADERS } from "../http/user-content";
 
 type ComputerPlacement = {
   placement: InteractionPlacement;
   placementInstanceId: string;
   session: BrowserControlPlacementSession;
   lease: LeaseSnapshot | null;
+  /** Current placement consent, separate from passive viewing authority. */
+  screenControlAllowed?: boolean;
 };
 
+const MODEL_COMPUTER_FRAME_MAX_BYTES = 256 * 1024;
+
+type ComputerFrameCaptureClient = {
+  capture(
+    targetId: string,
+    options: {
+      format?: "jpeg" | "png";
+      quality?: number;
+      maxWidth?: number;
+      maxHeight?: number;
+    },
+  ): Promise<ComputerControlFrame>;
+};
+
+export function validateComputerFrameForApi(
+  frame: Pick<ComputerControlFrame, "data" | "mediaType" | "metadataHeader">,
+  expected: ExpectedComputerFrameEvidence,
+): ComputerControlFrame {
+  return validateComputerControlFrameEvidence(frame, expected);
+}
+
+export async function captureModelComputerFrame(
+  sessionClient: ComputerFrameCaptureClient,
+  expected: ExpectedComputerFrameEvidence,
+): Promise<ComputerControlFrame> {
+  let captured = validateComputerFrameForApi(
+    await sessionClient.capture(expected.targetId, {
+      format: "jpeg",
+      quality: 55,
+      maxWidth: 1_024,
+      maxHeight: 768,
+    }),
+    expected,
+  );
+  if (captured.data.byteLength > MODEL_COMPUTER_FRAME_MAX_BYTES) {
+    captured = validateComputerFrameForApi(
+      await sessionClient.capture(expected.targetId, {
+        format: "jpeg",
+        quality: 30,
+        maxWidth: 640,
+        maxHeight: 480,
+      }),
+      expected,
+    );
+  }
+  if (captured.data.byteLength > MODEL_COMPUTER_FRAME_MAX_BYTES) {
+    throw new BrowserControlProtocolError(
+      "computer screenshot could not honor the model image byte bound",
+    );
+  }
+  return captured;
+}
+
+/** One validated screen frame, served as sandboxed, non-embeddable user content. */
+export function computerScreenshotResponse(
+  frame: Pick<ComputerControlFrame, "data" | "mediaType" | "metadataHeader">,
+): Response {
+  // Copy exactly the image bytes: a Node Buffer view may share a larger
+  // backing allocation, which `.slice().buffer` would expose whole.
+  return new Response(Uint8Array.from(frame.data).buffer, {
+    status: 200,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": frame.mediaType,
+      "x-opengeni-computer-frame": frame.metadataHeader,
+      ...USER_CONTENT_SECURITY_HEADERS,
+    },
+  });
+}
+
 /** Public ComputerSession resource surface. Physical app/window authority stays
  * in the same placement controller used by BrowserSession; this route owns only
  * durable authorization, placement fencing, lifecycle receipts, and routing. */
@@ -108,13 +213,15 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
   app.get("/v1/workspaces/:workspaceId/computer-sessions", async (context) => {
     const workspaceId = context.req.param("workspaceId") ?? "";
     const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:read");
+    const listed = await listComputerSessions(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
     return context.json(
-      ComputerSessionListResponse.parse(
-        await listComputerSessions(deps.db, {
-          accountId: grant.accountId,
-          workspaceId,
-        }),
-      ),
+      ComputerSessionListResponse.parse({
+        ...listed,
+        sessions: await filterInteractionSessionsForGrant(deps, grant, listed.sessions),
+      }),
     );
   });
 
@@ -141,8 +248,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     const request = await parseJsonBody(context, CreateComputerSessionRequest);
     const startedAtMs = performance.now();
     await authorizeSourceSession(deps, grant, request.sessionId, "session.control");
-    const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+    const origin = requestOrigin(context, deps.settings);
     const authority = controllerAuthorityRoot(deps);
+    let prepared: Awaited<ReturnType<typeof prepareComputerSessionCreate>> | null = null;
 
     try {
       const existing = await findComputerSessionControlRecordByOperation(deps.db, {
@@ -156,7 +264,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         );
       }
       if (existing) assertCreateReplay(request, existing.session);
-      let prepared = existing
+      prepared = existing
         ? await prepareComputerSessionCreate(
             deps.db,
             computerCreateInput(grant, workspaceId, request, existing.session.placement),
@@ -264,26 +372,27 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               () => placement,
             );
           } catch (error) {
-            if (
+            const retryableRequestFailure =
+              error instanceof BrowserControlRequestError &&
+              error.retryable &&
+              error.error.code !== "machine_locked";
+            const outcomeUnknown =
+              error instanceof BrowserControlProtocolError ||
               error instanceof BrowserControlTransportError ||
-              (error instanceof BrowserControlRequestError &&
-                error.retryable &&
-                error.error.code !== "machine_locked") ||
-              isAbort(error)
-            ) {
-              throw error;
-            }
+              isAbort(error);
+            const rethrowAfterFailure =
+              error instanceof BrowserControlTransportError ||
+              retryableRequestFailure ||
+              isAbort(error);
             const failed = await failComputerSessionOperation(deps.db, {
               accountId: grant.accountId,
               workspaceId,
               operationId: request.operationId,
               computerSessionId: preparedSession.id,
-              ...(error instanceof BrowserControlProtocolError
-                ? { state: "outcome_unknown" as const }
-                : {}),
+              ...(outcomeUnknown ? { state: "outcome_unknown" as const } : {}),
               error: interactionFailure(error),
             });
-            if (interactionHeld && !(error instanceof BrowserControlProtocolError)) {
+            if (interactionHeld && !outcomeUnknown) {
               await releaseInteractionHolder(
                 grant,
                 workspaceId,
@@ -291,6 +400,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
                 placement.placement,
               ).catch(() => undefined);
             }
+            if (rethrowAfterFailure) throw error;
             return failed;
           }
           // These facts come from the physical adapter after its native helper
@@ -320,10 +430,49 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         parsed.operation.state === "completed" && !parsed.operation.replayed ? 201 : 200,
       );
     } catch (error) {
+      if (prepared) {
+        // A concurrent dispatch owns its exact binding, even if this request's
+        // placement failed. Settle only the still-undispatched create receipt.
+        await failComputerSessionOperation(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          operationId: request.operationId,
+          computerSessionId: prepared.session.id,
+          onlyIfPreparedCreate: true,
+          error: interactionFailure(error),
+        }).catch(() => undefined);
+      }
       throw computerRouteError(error);
     }
   });
 
+  app.get(
+    "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/input-posture",
+    async (context) => {
+      const { workspaceId, grant, computerSessionId } = await routePreamble(
+        context,
+        "sessions:read",
+      );
+      const result = await withActiveComputerController(
+        context,
+        grant,
+        workspaceId,
+        computerSessionId,
+        "session.read",
+        "computer.read",
+        async ({ record, binding, placement }) =>
+          ComputerSessionInputPosture.parse({
+            computerSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            inputAllowed: await authorizeHumanFrameInput(grant, record, placement),
+          }),
+        false,
+      );
+      context.header("cache-control", "no-store");
+      return context.json(result);
+    },
+  );
+
   app.get(
     "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/targets",
     async (context) => {
@@ -370,6 +519,40 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     },
   );
 
+  app.get(
+    "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/targets/:targetId/screenshot",
+    async (context) => {
+      const { workspaceId, grant, computerSessionId } = await routePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const frame = await withActiveComputerController(
+        context,
+        grant,
+        workspaceId,
+        computerSessionId,
+        "session.read",
+        "computer.read",
+        async ({ sessionClient, binding }) => {
+          try {
+            return await captureModelComputerFrame(sessionClient, {
+              computerSessionId,
+              controllerGeneration: binding.controllerGeneration,
+              targetId,
+            });
+          } catch (error) {
+            if (error instanceof ComputerFrameEvidenceMismatchError) {
+              observeComputerFrameEvidenceMismatch(deps.observability, error.reason);
+            }
+            throw error;
+          }
+        },
+      );
+      return computerScreenshotResponse(frame);
+    },
+  );
+
   app.get(
     "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/clipboard",
     async (context) => {
@@ -406,8 +589,15 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         computerSessionId,
         "session.control",
         "computer.action",
-        async ({ sessionClient, binding }) =>
-          await sessionClient.action(
+        async ({ sessionClient, binding, record }) => {
+          if (
+            record.session.placement.kind === "sandbox_group" &&
+            deps.settings.sandboxDesktopInteractive === false &&
+            grant.principalKind !== "agent_attempt"
+          ) {
+            throw new HTTPException(403, { message: "Human desktop input is disabled" });
+          }
+          return await sessionClient.action(
             ComputerActionCommand.parse({
               protocolVersion: INTERACTION_PROTOCOL_VERSION,
               operationId: request.operationId,
@@ -420,7 +610,8 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               actor: interactionActorForGrant(grant),
               action: request.action,
             }),
-          ),
+          );
+        },
       );
       observeComputerActionResult(deps.observability, startedAtMs, request, result);
       return context.json(result);
@@ -452,7 +643,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/attachments",
     async (context) => {
       const { workspaceId, grant, computerSessionId } = await routePreamble(context, "stream:view");
-      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+      const origin = requestOrigin(context, deps.settings);
       const request = await parseJsonBody(context, ComputerSessionAttachmentRequest);
       const result = await withActiveComputerController(
         context,
@@ -463,25 +654,10 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         "computer.attach",
         async ({ client, sessionClient, record, binding, placement }) => {
           if (origin) await client.addAllowedOrigins([origin]);
-          const grantId = randomUUID();
-          const expiresAt = new Date(Date.now() + request.expiresInSeconds * 1_000).toISOString();
-          const token = deriveComputerViewGrantToken({
-            rootSecret: controllerAuthorityRoot(deps),
-            accountId: grant.accountId,
-            workspaceId,
-            placement: record.session.placement,
-            placementInstanceId: placement.placementInstanceId,
-            computerSessionId,
-            controllerGeneration: binding.controllerGeneration,
-            tokenGeneration: record.tokenGeneration,
-            grantId,
-            expiresAt,
-          });
           const reference = {
             computerSessionId,
             controllerGeneration: binding.controllerGeneration,
           };
-          await client.createComputerViewGrant(reference, { grantId, token, expiresAt });
           const target = (await sessionClient.listTargets()).find(
             (candidate) => candidate.id === request.targetId,
           );
@@ -492,6 +668,40 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               retryable: false,
             });
           }
+          if (target.kind === "app") {
+            throw new BrowserControlRequestError(409, {
+              code: "unsupported",
+              message:
+                "application targets support semantic control but do not provide a visual stream; select a window or screen",
+              retryable: false,
+            });
+          }
+          const grantId = randomUUID();
+          const expiresAt = new Date(Date.now() + request.expiresInSeconds * 1_000).toISOString();
+          const token = deriveComputerViewGrantToken({
+            rootSecret: controllerAuthorityRoot(deps),
+            accountId: grant.accountId,
+            workspaceId,
+            placement: record.session.placement,
+            placementInstanceId: placement.placementInstanceId,
+            computerSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            tokenGeneration: record.tokenGeneration,
+            grantId,
+            expiresAt,
+          });
+          // Keep the old strict-key request. Human input uses canonical
+          // actions; this grant authorizes only the frame producer. An older
+          // controller's reusable RFB bearer must stay behind the proxy.
+          const viewGrant = await client.createComputerViewGrant(reference, {
+            grantId,
+            token,
+            expiresAt,
+          });
+          const managedLinuxPlacement =
+            record.session.placement.kind === "sandbox_group" &&
+            record.session.platform === "linux";
+          const inputAllowed = await authorizeHumanFrameInput(grant, record, placement);
           const relaySecret = placement.session.openComputerFrames
             ? resolveStreamTokenSecret(deps.settings)
             : null;
@@ -510,15 +720,31 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               ...(request.stream ? { stream: request.stream } : {}),
             });
           } catch (error) {
+            const publicFailure = interactionControlApiError(error, "computer");
             console.error("computer frame relay open failed", {
               computerSessionId,
               targetId: request.targetId,
-              failure: error instanceof Error ? error.message : String(error),
+              failureCode: publicFailure?.details?.controlFailureCode ?? "unclassified",
+              retryable: publicFailure?.retryable ?? false,
+              outcomeUnknown: publicFailure?.outcomeUnknown ?? false,
+              controlRequestId: publicFailure?.details?.controlRequestId ?? null,
             });
             throw error;
           }
           const stream = relayed
             ? await (async () => {
+                // 0281: stamp the authenticated viewer subject and the live
+                // session authority epoch into the relay stream token.
+                const relayAuthorityEpoch = await getSessionAuthorityEpoch(deps.db, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  sessionId: record.sourceSessionId,
+                });
+                if (relayAuthorityEpoch === null) {
+                  throw new BrowserControlUnsupportedError(
+                    "stream authority is unavailable for this session",
+                  );
+                }
                 const relayToken = await mintStreamToken(relaySecret!, {
                   workspaceId,
                   sessionId: record.sourceSessionId,
@@ -526,6 +752,8 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
                   leaseEpoch: record.tokenGeneration,
                   port: relayed.channel.port,
                   ttlSeconds: request.expiresInSeconds,
+                  subjectId: grant.subjectId,
+                  authorityEpoch: relayAuthorityEpoch,
                 });
                 return {
                   kind: "relay" as const,
@@ -540,34 +768,48 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
                   },
                 };
               })()
-            : record.session.placement.kind === "sandbox_group" &&
-                record.session.platform === "linux" &&
-                target.kind === "screen"
-              ? {
-                  kind: "direct_rfb" as const,
-                  url: await client.computerRfbStreamUrl(reference, request.targetId),
-                  protocols: [
-                    "binary",
-                    COMPUTER_RFB_WEBSOCKET_PROTOCOL,
-                    `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
-                  ],
-                }
-              : {
-                  kind: "direct_websocket" as const,
-                  url: await client.computerFrameStreamUrl(
-                    reference,
-                    request.targetId,
-                    request.stream,
-                  ),
-                  protocols: [
-                    COMPUTER_CONTROL_WEBSOCKET_PROTOCOL,
-                    `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
-                  ],
-                };
+            : await (async () => {
+                const protocols = [
+                  COMPUTER_CONTROL_WEBSOCKET_PROTOCOL,
+                  `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
+                ];
+                const upstreamUrl = await client.computerFrameStreamUrl(
+                  reference,
+                  request.targetId,
+                  request.stream,
+                );
+                const attachment =
+                  (!viewGrant.scopedRfbInput && managedLinuxPlacement) ||
+                  placementUsesInteractionFrameProxy(placement.lease?.backend, {
+                    openSandboxSignedEndpoints: deps.settings.openSandboxSignedEndpoints,
+                    ...(typeof deps.settings.openSandboxInteractionFrameProxy === "boolean"
+                      ? {
+                          openSandboxInteractionFrameProxy:
+                            deps.settings.openSandboxInteractionFrameProxy,
+                        }
+                      : {}),
+                  })
+                    ? createInteractionFrameProxyAttachment({
+                        requestUrl: context.req.url,
+                        publicBaseUrl: deps.settings.publicBaseUrl,
+                        webBaseUrl: deps.settings.webBaseUrl,
+                        forwardedProto: context.req.header("x-forwarded-proto"),
+                        forwardedHost:
+                          context.req.header("x-forwarded-host") ?? context.req.header("host"),
+                        rootSecret: controllerAuthorityRoot(deps),
+                        upstreamUrl,
+                        upstreamProtocols: protocols,
+                        origin,
+                        expiresAt,
+                      })
+                    : { url: upstreamUrl, protocols };
+                return { kind: "direct_websocket" as const, ...attachment };
+              })();
           return ComputerSessionAttachment.parse({
             computerSessionId,
             controllerGeneration: binding.controllerGeneration,
             targetId: request.targetId,
+            inputAllowed,
             stream,
             expiresAt,
           });
@@ -577,6 +819,40 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     },
   );
 
+  async function authorizeHumanFrameInput(
+    grant: AccessGrant,
+    record: ComputerSessionControlRecord,
+    placement: ComputerPlacement,
+  ): Promise<boolean> {
+    if (
+      ((record.session.placement.kind === "connected_machine" ||
+        record.session.placement.kind === "attached_device") &&
+        placement.screenControlAllowed !== true) ||
+      (record.session.placement.kind === "sandbox_group" &&
+        deps.settings.sandboxDesktopInteractive === false) ||
+      grant.principalKind === "agent_attempt" ||
+      !hasPermission(grant.permissions, "sessions:control")
+    )
+      return false;
+    try {
+      await requireSessionAuthorization(deps, grant, {
+        sessionId: record.sourceSessionId,
+        operation: "session.control",
+        surface: "http",
+      });
+      return true;
+    } catch (error) {
+      // Input availability cannot invalidate an independently authorized view.
+      // Every action reauthorizes the live source instead of trusting this hint.
+      if (
+        error instanceof SessionAuthorizationDeniedError ||
+        error instanceof SessionAuthorizationUnavailableError
+      )
+        return false;
+      throw error;
+    }
+  }
+
   app.post(
     "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/heartbeat",
     async (context) => {
@@ -614,7 +890,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       const computerSessionId = requireUuidParam(context, "computerSessionId");
       const request = await parseJsonBody(context, ComputerSessionLifecycleRequest);
       const startedAtMs = performance.now();
-      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
+      const origin = requestOrigin(context, deps.settings);
       try {
         const before = await getComputerSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -765,23 +1041,42 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       if (device.state !== "connected") {
         throw new ComputerSessionStateError("Attached browser machine is disconnected");
       }
-      const enrollment = await getEnrollment(
+      const enrollment = await getLiveEnrollmentConnection(
         deps.db,
         sourceSession.workspaceId,
         device.enrollmentId,
       );
-      if (!enrollment || enrollment.status !== "active") {
+      if (!enrollment || enrollment.status !== "active" || !enrollment.connectionInstanceId) {
         throw new ComputerSessionStateError("Attached browser machine is unavailable");
       }
-      assertPlacementInstance(expectedPlacementInstanceId, device.connectionGeneration);
+      if (!enrollment.workspaceRoot) {
+        throw new ComputerSessionStateError(
+          "Attached browser machine has not reported an absolute workspace root",
+        );
+      }
+      if (operation !== "computer.end") {
+        assertConnectedMachineComputerAccess(enrollment, operation);
+      }
+      const placementInstanceId = attachedEndPlacementInstanceId(
+        operation,
+        expectedPlacementInstanceId,
+        device.connectionGeneration,
+      );
       const built = await buildSelfhostedBackendSession({
         workspaceId: sourceSession.workspaceId,
         agentId: device.enrollmentId,
+        connectionInstanceId: enrollment.connectionInstanceId,
+        workspaceRoot: enrollment.workspaceRoot,
         relay: relayConfigFromSettings(deps.settings),
         controlRpcFactory: () => new NatsControlRpc(async () => deps.bus.getRequestConnection()),
         epoch: 0,
         timeoutMs: deps.settings.sandboxSelfhostedControlTimeoutMs,
         execTimeoutMs: deps.settings.sandboxSelfhostedExecTimeoutMs,
+        operationResourcePolicy: enrollment.operationPolicy,
+        operationResourcePolicySupported:
+          enrollment.agentCapabilities.operationResourcePolicy === true,
+        operationCpuQuotaSupported: enrollment.agentCapabilities.operationCpuQuota === true,
+        transactionalFsWriteSupported: enrollment.agentCapabilities.transactionalFsWrite === true,
         ...(deps.settings.agentOpStreamEnabled === true &&
         enrollment.opStream === true &&
         deps.bus.getOpStreamConnection
@@ -797,9 +1092,10 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       waitSignal.throwIfAborted();
       return await callback({
         placement: expectedPlacement,
-        placementInstanceId: device.connectionGeneration,
+        placementInstanceId,
         session: built.session as unknown as BrowserControlPlacementSession,
         lease: null,
+        screenControlAllowed: enrollment.allowScreenControl === true,
       });
     }
     const runWithChannelA =
@@ -819,6 +1115,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         waitSignal,
         operation,
         retryControllerTransport: operation === "computer.read" || operation === "computer.action",
+        ...(expectedPlacementInstanceId && expectedPlacement?.kind === "sandbox_group"
+          ? { retainedInstanceId: expectedPlacementInstanceId }
+          : {}),
       },
       async (handle) => {
         if (expectedPlacement?.kind === "sandbox_group") {
@@ -838,13 +1137,38 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         }
 
         const resolved = await handle.routingSession.prime();
+        let screenControlAllowed = false;
+        if (operation !== "computer.end" && resolved.kind === "selfhosted" && resolved.sandboxId) {
+          const sandbox = await getSandbox(deps.db, grant, resolved.sandboxId);
+          if (sandbox?.kind !== "selfhosted" || !sandbox.enrollmentId) {
+            throw new ComputerSessionStateError("Connected Machine placement is unavailable");
+          }
+          const enrollment = await getLiveEnrollmentConnection(
+            deps.db,
+            grant,
+            sandbox.enrollmentId,
+          );
+          if (!enrollment?.connectionInstanceId) {
+            throw new ComputerSessionStateError("Connected Machine is unavailable");
+          }
+          assertConnectedMachineComputerAccess(enrollment, operation);
+          screenControlAllowed = enrollment.allowScreenControl === true;
+        }
         if (expectedPlacement?.kind === "connected_machine") {
           if (
             resolved.kind !== "selfhosted" ||
             resolved.sandboxId !== expectedPlacement.sandboxId
           ) {
-            throw new ComputerSessionStateError(
-              "ComputerSession Connected Machine is not the active placement",
+            if (operation === "computer.create") {
+              throw new HTTPException(422, {
+                message:
+                  "The requested Connected Machine is not this session's current placement. Move the session to that machine before creating an interaction resource.",
+              });
+            }
+            return await throwComputerSourcePlacementChanged(
+              grant,
+              sourceSession.id,
+              expectedPlacement.sandboxId,
             );
           }
           const placementInstanceId = resolved.providerInstanceId ?? expectedPlacement.sandboxId;
@@ -854,6 +1178,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             placementInstanceId,
             session: resolved.session as unknown as BrowserControlPlacementSession,
             lease: null,
+            screenControlAllowed,
           });
         }
         if (resolved.sandboxId === null) {
@@ -878,10 +1203,14 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         }
         if (resolved.kind === "selfhosted") {
           return await callback({
-            placement: { kind: "connected_machine", sandboxId: resolved.sandboxId },
+            placement: {
+              kind: "connected_machine",
+              sandboxId: resolved.sandboxId,
+            },
             placementInstanceId: resolved.providerInstanceId ?? resolved.sandboxId,
             session: resolved.session as unknown as BrowserControlPlacementSession,
             lease: null,
+            screenControlAllowed,
           });
         }
         throw new BrowserControlUnsupportedError(
@@ -914,7 +1243,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       !lease ||
       (lease.liveness !== "warm" && lease.liveness !== "draining") ||
       lease.instanceId !== binding.placementInstanceId ||
-      !lease.controllerDataPlaneUrl
+      !lease.controllerDataPlaneUrl ||
+      (lease.backend === "opensandbox" && deps.settings.openSandboxSignedEndpoints) ||
+      !controllerCachedUrlIsUsable(lease.controllerDataPlaneUrl)
     ) {
       return null;
     }
@@ -938,8 +1269,29 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     ) {
       return placement;
     }
+    if (placement.lease.backend === "opensandbox" && deps.settings.openSandboxSignedEndpoints) {
+      if (!placement.lease.controllerDataPlaneUrl) return placement;
+      const lease = await recordLeaseControllerDataPlaneUrl(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sandboxGroupId: placement.placement.sandboxGroupId,
+        expectedEpoch: placement.lease.leaseEpoch,
+        expectedInstanceId: placement.lease.instanceId,
+        controllerDataPlaneUrl: null,
+      });
+      return lease ? { ...placement, lease } : placement;
+    }
     const endpoint = await placement.session.resolveExposedPort(BROWSER_CONTROL_PORT);
     const url = buildStreamUrl(endpoint);
+    if (
+      !shouldPersistControllerDataPlaneUrl({
+        backend: placement.lease.backend,
+        signedEndpoints: deps.settings.openSandboxSignedEndpoints,
+        url,
+      })
+    ) {
+      return placement;
+    }
     const lease = await recordLeaseControllerDataPlaneUrl(deps.db, {
       accountId: grant.accountId,
       workspaceId,
@@ -949,6 +1301,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       controllerDataPlaneUrl: url,
     });
     if (!lease) return placement;
+    if (!controllerCacheAllowsHostFetch(url)) {
+      return { ...placement, lease };
+    }
     return { ...placement, session: controllerOnlySession(url), lease };
   }
 
@@ -964,7 +1319,13 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     const sandboxGroupId =
       placement.placement.kind === "sandbox_group" ? placement.placement.sandboxGroupId : null;
     return await withCachedController({
-      cachedUrl: sandboxGroupId ? (cachedUrl ?? null) : null,
+      cachedUrl:
+        sandboxGroupId &&
+        cachedUrl &&
+        !(placement.lease?.backend === "opensandbox" && deps.settings.openSandboxSignedEndpoints) &&
+        controllerCachedUrlIsUsable(cachedUrl)
+          ? cachedUrl
+          : null,
       createCachedClient: (url) =>
         new BrowserControlClient(controllerOnlySession(url), { adminToken }),
       prepareCachedClient: async (client) => {
@@ -1016,6 +1377,17 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         computerSessionId,
       });
       await authorizeSourceSession(deps, grant, record.sourceSessionId, authorizationOperation);
+      let sourceSession: Session | null = null;
+      if (record.session.placement?.kind === "connected_machine") {
+        sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
+        if (sourceSession.activeSandboxId !== record.session.placement.sandboxId) {
+          return await throwComputerSourcePlacementChanged(
+            grant,
+            record.sourceSessionId,
+            record.session.placement.sandboxId,
+          );
+        }
+      }
       if (record.session.lifecycle !== "active" || !record.session.controller) {
         throw new ComputerSessionStateError("ComputerSession is not active");
       }
@@ -1096,7 +1468,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         }
       }
 
-      const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
+      sourceSession ??= await requireSourceSession(deps, workspaceId, record.sourceSessionId);
       return await withComputerPlacement(
         sourceSession,
         grant,
@@ -1116,6 +1488,25 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     }
   }
 
+  async function throwComputerSourcePlacementChanged(
+    grant: AccessGrant,
+    sourceSessionId: string,
+    connectedSandboxId: string,
+  ): Promise<never> {
+    const reconciliation = await terminalizeStaleConnectedInteractionPlacement(deps.db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      sourceSessionId,
+      connectedSandboxId,
+    });
+    if (reconciliation.sourcePlacementChanged) {
+      throw sourcePlacementChangedApiError("computer_session");
+    }
+    throw new ComputerSessionStateError(
+      "ComputerSession source placement changed during the request; retry",
+    );
+  }
+
   async function ensureInteractionHolder(
     grant: AccessGrant,
     sourceSession: Session,
@@ -1127,6 +1518,11 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     if (!placement.lease?.instanceId) {
       throw new ComputerSessionStateError("ComputerSession lease placement is unavailable");
     }
+    const sandboxRuntime = await resolveSessionSandboxRuntime(
+      deps.db,
+      deps.settings,
+      sourceSession,
+    );
     const acquired = await acquireLease(deps.db, {
       accountId: grant.accountId,
       workspaceId: sourceSession.workspaceId,
@@ -1135,9 +1531,14 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       holderId: interactionHolderId(computerSessionId),
       subjectId: sourceSession.id,
       backend: placement.lease.backend,
+      warmBilling: {
+        mode: deps.settings.sandboxWarmBillingMode,
+        rateMicrosPerSecond: sandboxWarmRateMicrosPerSecond(deps.settings, placement.lease.backend),
+      },
       os: placement.lease.os,
-      image: placement.lease.image,
-      rigVersionId: placement.lease.rigVersionId,
+      image: sandboxRuntime.image,
+      imagePolicy: "new_creates_only",
+      rigVersionId: sourceSession.rigVersionId,
       leaseTtlMs: deps.settings.sandboxLeaseTtlMs,
       expectedEpoch: placement.lease.leaseEpoch,
       waitSignal,
@@ -1158,6 +1559,11 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       ).catch(() => undefined);
       throw new ComputerSessionStateError("ComputerSession placement fence changed; retry");
     }
+    await renewSandboxProviderExpiration({
+      backend: acquired.lease.backend as ApiRouteDeps["settings"]["sandboxBackend"],
+      settings: deps.settings,
+      instanceId: acquired.lease.instanceId,
+    }).catch(() => false);
     return true;
   }
 
@@ -1273,7 +1679,11 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
   async function routePreamble(
     context: Context,
     permission: "sessions:read" | "sessions:control" | "stream:view",
-  ): Promise<{ workspaceId: string; grant: AccessGrant; computerSessionId: string }> {
+  ): Promise<{
+    workspaceId: string;
+    grant: AccessGrant;
+    computerSessionId: string;
+  }> {
     const workspaceId = context.req.param("workspaceId") ?? "";
     const grant = await requireAccessGrant(context, deps, workspaceId, permission);
     return {
@@ -1284,6 +1694,21 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
   }
 }
 
+function sourcePlacementChangedApiError(interactionResource: "computer_session"): ApiHttpError {
+  return new ApiHttpError(409, {
+    code: "conflict",
+    message:
+      "This Desktop belonged to a previous task placement and was retired. Open a new Desktop.",
+    retryable: false,
+    outcomeUnknown: false,
+    details: {
+      interactionResource,
+      interactionFailureCode: "source_placement_changed",
+      interactionLifecycle: "lost",
+    },
+  });
+}
+
 function computerCreateInput(
   grant: AccessGrant,
   workspaceId: string,
@@ -1400,7 +1825,10 @@ async function authorizeSourceSession(
     });
   } catch (error) {
     if (error instanceof SessionAuthorizationDeniedError) {
-      throw new HTTPException(404, { message: "session not found", cause: error });
+      throw new HTTPException(404, {
+        message: "session not found",
+        cause: error,
+      });
     }
     if (error instanceof SessionAuthorizationUnavailableError) {
       throw new HTTPException(503, {
@@ -1456,26 +1884,8 @@ function requireOpaqueParam(context: Context, name: string): string {
   return value;
 }
 
-function requestOrigin(context: Context, allowedPattern: string): string | null {
-  const value = context.req.header("origin");
-  if (!value) return null;
-  let url: URL;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new HTTPException(400, { message: "invalid request origin" });
-  }
-  if (
-    url.origin === "null" ||
-    (url.protocol !== "http:" && url.protocol !== "https:") ||
-    url.origin !== value
-  ) {
-    throw new HTTPException(400, { message: "invalid request origin" });
-  }
-  if (!allowedCorsOrigin(allowedPattern, url.origin)) {
-    throw new HTTPException(403, { message: "request origin is not allowed" });
-  }
-  return url.origin;
+function requestOrigin(context: Context, settings: ApiRouteDeps["settings"]): string | null {
+  return validateInteractionRequestOrigin(context.req.header("origin"), settings);
 }
 
 function interactionActorForGrant(grant: AccessGrant): ReturnType<typeof InteractionActor.parse> {
@@ -1501,6 +1911,39 @@ function assertPlacementInstance(expected: string | null, actual: string): void
   }
 }
 
+/** End must still reach the live agent with the session's original token
+ *  fence. A later Chrome generation must not block ScreenCaptureKit teardown. */
+function attachedEndPlacementInstanceId(
+  operation: ChannelAOperation,
+  expectedPlacementInstanceId: string | null,
+  liveGeneration: string,
+): string {
+  if (operation === "computer.end" && expectedPlacementInstanceId) {
+    return expectedPlacementInstanceId;
+  }
+  assertPlacementInstance(expectedPlacementInstanceId, liveGeneration);
+  return liveGeneration;
+}
+
+function assertConnectedMachineComputerAccess(
+  enrollment: {
+    hasDisplay: boolean;
+    desktopUnavailableReason: string | null;
+    allowScreenControl: boolean;
+  },
+  operation: ChannelAOperation,
+): void {
+  const error = connectedMachineComputerAccessError(
+    enrollment,
+    operation === "computer.action" || operation === "computer.control",
+  );
+  if (!error) return;
+  if (error.status === 403) {
+    throw new HTTPException(403, { message: error.message });
+  }
+  throw new ComputerSessionStateError(error.message);
+}
+
 function isTerminalOperation(state: string): boolean {
   return state === "completed" || state === "failed" || state === "outcome_unknown";
 }
@@ -1521,7 +1964,11 @@ function interactionFailure(error: unknown) {
     error instanceof BrowserControlUnsupportedError ||
     error instanceof BrowserControlServerUnsupportedError
   ) {
-    return { code: "unsupported" as const, message: error.message, retryable: false };
+    return {
+      code: "unsupported" as const,
+      message: error.message,
+      retryable: false,
+    };
   }
   if (error instanceof BrowserControlServerError) {
     return {
@@ -1541,7 +1988,11 @@ function interactionFailure(error: unknown) {
 }
 
 function computerRouteError(error: unknown): HTTPException {
+  const connectedMachineError = interactionControlApiError(error, "computer");
+  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 ComputerSessionNotFoundError) {
     return new HTTPException(404, { message: error.message, cause: error });
   }