@opengeni/api-router 2.11.3 → 2.12.3-canary.0

package/src/routes/scheduled-tasks.ts

@@ -7,7 +7,11 @@ import {
 import { listScheduledTaskRuns, listScheduledTasks } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant, resolveWorkspaceCatalogSettings } from "@opengeni/core";
+import {
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  resolveWorkspaceCatalogSettings,
+} from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
@@ -35,7 +39,13 @@ export function registerScheduledTaskRoutes(app: Hono, deps: ApiRouteDeps): void
 
   app.post("/v1/workspaces/:workspaceId/scheduled-tasks", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "scheduled_tasks:manage");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "scheduled_tasks:manage",
+    );
+    const grant = authorization.grant;
     const rawPayload = await c.req.json();
     const parsedPayload = CreateScheduledTaskRequest.safeParse(rawPayload);
     if (!parsedPayload.success) {
@@ -61,6 +71,7 @@ export function registerScheduledTaskRoutes(app: Hono, deps: ApiRouteDeps): void
       db,
       objectStorage,
       grant,
+      authorization,
       payload,
       toolsProvided: scheduledTaskToolsProvided(rawPayload),
       sessionAuthorization: deps.sessionAuthorization,
@@ -103,7 +114,13 @@ export function registerScheduledTaskRoutes(app: Hono, deps: ApiRouteDeps): void
 
   app.patch("/v1/workspaces/:workspaceId/scheduled-tasks/:taskId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "scheduled_tasks:manage");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "scheduled_tasks:manage",
+    );
+    const grant = authorization.grant;
     const taskId = c.req.param("taskId");
     const existing = await requireScheduledTaskForApi(db, workspaceId, taskId);
     const previous = await captureScheduledTaskRestoreState(db, existing);
@@ -127,6 +144,7 @@ export function registerScheduledTaskRoutes(app: Hono, deps: ApiRouteDeps): void
       objectStorage,
       grant,
       existing,
+      authorization,
       payload,
       toolsProvided: scheduledTaskToolsProvided(rawPayload),
       sessionAuthorization: deps.sessionAuthorization,
@@ -151,7 +169,13 @@ export function registerScheduledTaskRoutes(app: Hono, deps: ApiRouteDeps): void
 
   app.post("/v1/workspaces/:workspaceId/scheduled-tasks/:taskId/resume", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "scheduled_tasks:manage");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "scheduled_tasks:manage",
+    );
+    const grant = authorization.grant;
     const existing = await requireScheduledTaskForApi(db, workspaceId, c.req.param("taskId"));
     const previous = await captureScheduledTaskRestoreState(db, existing);
     const catalogSettings = (
@@ -167,6 +191,7 @@ export function registerScheduledTaskRoutes(app: Hono, deps: ApiRouteDeps): void
       grant,
       existing,
       payload: { status: "active" },
+      authorization,
       sessionAuthorization: deps.sessionAuthorization,
       authorizationSurface: "http",
     });

package/src/routes/sessions.ts

@@ -49,9 +49,7 @@ import {
   SessionEventReadMode,
   SessionEventLatestClass,
   SessionEventResultMode,
-  SessionEndUser,
-  SESSION_END_USER_ID_MAX_CHARS,
-  SESSION_END_USER_SOURCE_MAX_CHARS,
+  SessionScopeSubjectId,
   SessionEventSemanticClass,
   SessionEventType,
   SessionMcpServerId,
@@ -214,6 +212,10 @@ import {
   GatewayRealtimeBrokerError,
 } from "../gateway-realtime";
 import { createXaiRealtimeConnectionSecret, XaiRealtimeBrokerError } from "../xai-realtime";
+import {
+  prepareExternalLinkTurnAdmission,
+  externalContinuationCommitAuthorizer,
+} from "@opengeni/core";
 import { z, ZodError } from "zod";
 import {
   runConcurrentChannelAReads,
@@ -240,6 +242,7 @@ import {
   requireAccessGrant,
   requireAccessGrantAuthorization,
   requireFreshAccessGrant,
+  hasVerifiedOwningUserAuthorization,
   requirePermission,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
@@ -639,6 +642,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           workspaceId,
           payload,
           authorization.canonicalManagedHumanSession,
+          authorization,
         ),
       );
     } catch (error) {
@@ -700,12 +704,12 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         ...(query.updatedBefore ? { updatedBefore: query.updatedBefore } : {}),
         ...(query.createdFrom ? { createdFrom: query.createdFrom } : {}),
         ...(query.createdBefore ? { createdBefore: query.createdBefore } : {}),
-        ...(query.endUser ? { endUser: query.endUser } : {}),
+        ...(query.scopeSubjectId ? { scopeSubjectId: query.scopeSubjectId } : {}),
         ...(authorizationScope ? { authorizationScope } : {}),
         // A managed human's own personal workspace has no membership row, so
         // the list's removal fence must fall back to the organization-membership
-        // pointer — for the canonical managed-cookie session that owns it only.
-        personalWorkspaceOwnerException: authorization.canonicalManagedHumanSession,
+        // pointer, only with verified native or external owning-user provenance.
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
       });
     } catch (error) {
       if (error instanceof SessionListAccessError) {
@@ -1672,7 +1676,15 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       const workspaceId = c.req.param("workspaceId");
       const sessionId = c.req.param("sessionId");
       const realtimeId = c.req.param("realtimeId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "sessions:control",
+      );
+      const grant = authorization.grant;
+      const beforeCommit = externalContinuationCommitAuthorizer(authorization);
+      const captureLinked = prepareExternalLinkTurnAdmission(authorization);
       if (
         !z.string().uuid().safeParse(sessionId).success ||
         !z.string().uuid().safeParse(realtimeId).success
@@ -1688,16 +1700,29 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         });
       }
       try {
-        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
-          syncSessionRealtimeLedgerInTransaction(scopedDb, {
-            workspaceId,
-            sessionId,
-            realtimeId,
-            ownerSubjectId: grant.subjectId,
-            ...parsed.data,
-            controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
-          }),
-        );
+        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) => {
+          // Acquire origin authority before inference/session locks. A deferred
+          // realtime session has no initial worker turn; capture its exact
+          // linked actor when the ledger actually admits ordinary agent work.
+          await beforeCommit?.(scopedDb as unknown as Database);
+          return syncSessionRealtimeLedgerInTransaction(
+            scopedDb,
+            {
+              workspaceId,
+              sessionId,
+              realtimeId,
+              ownerSubjectId: grant.subjectId,
+              ...parsed.data,
+              controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
+            },
+            captureLinked
+              ? {
+                  afterDelegationAdmission: async ({ turnId }) =>
+                    captureLinked(scopedDb as unknown as Database, sessionId, turnId),
+                }
+              : {},
+          );
+        });
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
         c.header("cache-control", "private, no-store");
         return c.json({ accepted: result.accepted, outbound: result.outbound });
@@ -1733,7 +1758,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         subjectId: grant.subjectId,
         sessionId,
         // Same owner-only personal-workspace fallback as the list above.
-        personalWorkspaceOwnerException: authorization.canonicalManagedHumanSession,
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
         ...parsed.data,
       });
       if (!session) {
@@ -1790,7 +1815,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         workspaceId,
         subjectId: grant.subjectId,
         sessionId,
-        personalWorkspaceOwnerException: authorization.canonicalManagedHumanSession,
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
         ...parsed.data,
       });
       if (!session) throw new HTTPException(404, { message: "session not found" });
@@ -1840,7 +1865,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         workspaceId,
         subjectId: grant.subjectId,
         sessionId,
-        personalWorkspaceOwnerException: authorization.canonicalManagedHumanSession,
+        personalWorkspaceOwnerException: hasVerifiedOwningUserAuthorization(authorization),
         ...parsed.data,
       });
       if (!session) throw new HTTPException(404, { message: "session not found" });
@@ -3064,6 +3089,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         latencyMode: payload.latencyMode ?? null,
         mcpCredentialUpdates: payload.mcpCredentialUpdates ?? [],
         connectionAuthorities: payload.connectionAuthorities,
+        ...(payload.selectedHostMcpDelegations
+          ? { selectedHostMcpDelegations: payload.selectedHostMcpDelegations }
+          : {}),
         ...(payload.personalResourceAttachment
           ? { personalResourceAttachment: payload.personalResourceAttachment }
           : {}),
@@ -3146,6 +3174,9 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           latencyMode: event.payload.latencyMode ?? null,
           mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
           connectionAuthorities: event.payload.connectionAuthorities,
+          ...(event.payload.selectedHostMcpDelegations
+            ? { selectedHostMcpDelegations: event.payload.selectedHostMcpDelegations }
+            : {}),
           ...(event.payload.personalResourceAttachment
             ? { personalResourceAttachment: event.payload.personalResourceAttachment }
             : {}),
@@ -4740,7 +4771,7 @@ function sessionListQuery(
   updatedBefore: Date | undefined;
   createdFrom: Date | undefined;
   createdBefore: Date | undefined;
-  endUser: SessionEndUser | undefined;
+  scopeSubjectId: SessionScopeSubjectId | undefined;
   hasPageFilters: boolean;
 } {
   const parentSessionId = query.parentSessionId;
@@ -4836,22 +4867,20 @@ function sessionListQuery(
   }
   // The opaque end-user label filter is an exact pair: one half alone is a
   // client error rather than a silently unfiltered list.
-  const endUserSource = query.endUserSource;
-  const endUserId = query.endUserId;
-  if ((endUserSource === undefined) !== (endUserId === undefined)) {
+  if (query.endUserSource !== undefined || query.endUserId !== undefined) {
     throw new HTTPException(400, {
-      message: "endUserSource and endUserId must be supplied together",
+      message: "Use canonical scopeSubjectId, not an external-user label",
     });
   }
-  let endUser: SessionEndUser | undefined;
-  if (endUserSource !== undefined && endUserId !== undefined) {
-    const parsedEndUser = SessionEndUser.safeParse({ source: endUserSource, id: endUserId });
+  let scopeSubjectId: SessionScopeSubjectId | undefined;
+  if (query.scopeSubjectId !== undefined) {
+    const parsedEndUser = SessionScopeSubjectId.safeParse(query.scopeSubjectId);
     if (!parsedEndUser.success) {
       throw new HTTPException(400, {
-        message: `endUserSource must be 1-${SESSION_END_USER_SOURCE_MAX_CHARS} and endUserId 1-${SESSION_END_USER_ID_MAX_CHARS} well-formed characters`,
+        message: "scopeSubjectId must be a canonical OpenGeni user subject",
       });
     }
-    endUser = parsedEndUser.data;
+    scopeSubjectId = parsedEndUser.data;
   }
   const hasPageFilters =
     originSiteId !== undefined ||
@@ -4861,7 +4890,7 @@ function sessionListQuery(
     updatedBefore !== undefined ||
     createdFrom !== undefined ||
     createdBefore !== undefined ||
-    endUser !== undefined;
+    scopeSubjectId !== undefined;
   if (pinsOnly && !allowCursor) {
     throw new HTTPException(400, { message: 'pinsOnly requires view="page"' });
   }
@@ -4895,7 +4924,7 @@ function sessionListQuery(
     updatedBefore,
     createdFrom,
     createdBefore,
-    endUser,
+    scopeSubjectId,
     hasPageFilters,
   };
 }

package/src/routes/social.ts

@@ -19,6 +19,7 @@ import { requireAccessGrant, requireAccessGrantAuthorization } from "@opengeni/c
 import {
   assertPersonalConnectionOwnerPrincipal,
   isPersonalConnectionOwnerPrincipal,
+  requireLegacyOAuthActor,
 } from "../connection-ownership";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { boundedLimit } from "../http/common";
@@ -111,6 +112,7 @@ export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
     // The contract already defaults this request to workspace ownership; an
     // explicit personal choice still needs a human who can own it.
+    requireLegacyOAuthActor(access);
     const personalOwnershipAllowed = isPersonalConnectionOwnerPrincipal(access);
     if (payload.ownership === "personal") {
       assertPersonalConnectionOwnerPrincipal(access);
@@ -140,7 +142,9 @@ export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
         requestUrl: c.req.url,
       },
     );
-    return c.redirect(result.redirectTo, 302);
+    return result.exactReturn
+      ? new Response(null, { status: 302, headers: { location: result.redirectTo } })
+      : c.redirect(result.redirectTo, 302);
   });
 
   app.get("/v1/workspaces/:workspaceId/social/posts", async (c) => {

package/src/routes/supergrok.ts

@@ -30,10 +30,19 @@ import {
   updateXaiRotationSettings,
   upsertXaiSubscriptionCredential,
   wakeXaiCapacityWaiters,
+  encryptEnvironmentValue,
+  decryptEnvironmentValue,
+  getWorkspaceGrant,
   type XaiSubscriptionAccountMetadata,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
-import { getManagedSession, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  getManagedSession,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  externalActorContinuationForAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
 import {
   XAI_CLIENT_VERSION,
   XaiSubscriptionError,
@@ -50,11 +59,14 @@ import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import * as z from "zod/v4";
 import { projectClientModel } from "../model-catalog";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { requireConnectOwnerAuthority } from "../integrations/connect-authority";
 
 type XaiAuthoritySnapshot = XaiProviderAccountAuthoritySnapshotV1;
 type ManagedCookieHuman = { subjectId: string };
 
 type SuperGrokConnectState = {
+  externalContinuationEncrypted?: string;
   workspaceId: string;
   scope: "workspace" | "user";
   subjectId: string;
@@ -132,8 +144,28 @@ async function requirePrivateHuman(
   workspaceId: string,
 ): Promise<{ accountId: string; subjectId: string }> {
   if (c.req.header("authorization")) {
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "connections:write",
+    );
+    const external = externalActorContinuationForAuthorization(authorization);
+    if (
+      external &&
+      authorization.contextIntegrity &&
+      external.actor.effectiveSubjectId === authorization.grant.subjectId
+    ) {
+      // The existing xAI user-pool domain requires an ordinary workspace
+      // membership, not just the synthetic Personal-workspace owner grant.
+      if (!(await getWorkspaceGrant(deps.db, authorization.grant.subjectId, workspaceId)))
+        throw new HTTPException(409, {
+          message: "Private SuperGrok accounts require membership in an ordinary workspace",
+        });
+      return { accountId: authorization.grant.accountId, subjectId: authorization.grant.subjectId };
+    }
     throw new HTTPException(403, {
-      message: "authorization bearer is not allowed for private SuperGrok accounts",
+      message: "Private SuperGrok accounts require a verified owning user",
     });
   }
   const human = await managedCookieHuman(c, deps);
@@ -148,6 +180,10 @@ async function requirePrivateHuman(
       message: "managed browser identity mismatch",
     });
   }
+  if (!(await getWorkspaceGrant(deps.db, grant.subjectId, workspaceId)))
+    throw new HTTPException(409, {
+      message: "Private SuperGrok accounts require membership in an ordinary workspace",
+    });
   return { accountId: grant.accountId, subjectId: grant.subjectId };
 }
 
@@ -160,7 +196,9 @@ export async function requireScopeMutation(
   if (scope === "organization")
     throw new HTTPException(409, { message: "Manage this subscription in organization settings" });
   if (scope === "user") {
-    requireSameOriginBrowserMutation(c, deps);
+    // Server-side external-user assertions do not use browser cookies. Ordinary
+    // bearers remain rejected by requirePrivateHuman; native CSRF is unchanged.
+    if (!c.req.header("authorization")) requireSameOriginBrowserMutation(c, deps);
     return await requirePrivateHuman(c, deps, workspaceId);
   }
   const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
@@ -509,6 +547,16 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
     const parsed = connectStartBody.safeParse(await c.req.json().catch(() => ({})));
     if (!parsed.success) throw new HTTPException(400, { message: "invalid SuperGrok scope" });
     const authority = await requireScopeMutation(c, deps, workspaceId, parsed.data.scope);
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      parsed.data.scope === "workspace" ? "workspace:admin" : "connections:write",
+    );
+    const continuation = externalActorContinuationForAuthorization(authorization);
+    const encryptionKey = environmentsEncryptionKeyBytes(deps.settings);
+    if (continuation && !encryptionKey)
+      throw new HTTPException(503, { message: "Credential encryption is unavailable" });
     try {
       const start = await requestXaiDeviceCode({
         fetch: (deps.xaiFetch ?? fetch) as XaiFetch,
@@ -528,6 +576,14 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
           deviceCode: start.deviceCode,
           intervalSeconds: start.intervalSeconds,
           expiresAt,
+          ...(continuation
+            ? {
+                externalContinuationEncrypted: encryptEnvironmentValue(
+                  encryptionKey!,
+                  JSON.stringify(continuation),
+                ),
+              }
+            : {}),
         }),
       });
     } catch (error) {
@@ -563,6 +619,30 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "SuperGrok connect identity changed",
       });
     }
+    const originKey = environmentsEncryptionKeyBytes(deps.settings);
+    const origin =
+      state.externalContinuationEncrypted && originKey
+        ? ExternalActorContinuation.parse(
+            JSON.parse(decryptEnvironmentValue(originKey, state.externalContinuationEncrypted)),
+          )
+        : null;
+    if (state.externalContinuationEncrypted && !origin)
+      throw new HTTPException(503, { message: "Connection origin unavailable" });
+    const requireOrigin = async () => {
+      if (origin)
+        await requireConnectOwnerAuthority(
+          deps.db,
+          {
+            accountId: authority.accountId,
+            workspaceId,
+            subjectId: authority.subjectId,
+            externalContinuation: origin,
+          },
+          state.scope === "workspace" ? "workspace:admin" : "connections:write",
+          origin,
+        );
+    };
+    await requireOrigin();
     if (Math.floor(Date.now() / 1_000) >= state.expiresAt) {
       return c.json({ status: "expired" as const });
     }
@@ -579,6 +659,13 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
       phase = "token_identity";
       const identity = xaiIdentityFromDeviceTokens(poll.tokens);
       phase = "credential_persist";
+      await requireOrigin();
+      const liveAuthority = await requireScopeMutation(c, deps, workspaceId, state.scope);
+      if (
+        liveAuthority.accountId !== authority.accountId ||
+        liveAuthority.subjectId !== authority.subjectId
+      )
+        throw new HTTPException(403, { message: "SuperGrok connection identity changed" });
       const encryptionKey = environmentsEncryptionKeyBytes(deps.settings);
       if (!encryptionKey) {
         throw new HTTPException(500, {

package/src/routes/workspaces.ts

@@ -89,6 +89,8 @@ import {
   accountScopedApiKeyWorkspaceAuthority,
   hasPermission,
   requireAccessContext,
+  listExternalActorWorkspaces,
+  addExternalWorkspaceMemberForRequest,
   requireAccessGrant,
   requireWorkspaceSettingsGrant,
   requireFreshAccessGrant,
@@ -200,12 +202,25 @@ export function workspaceUpdateRequestsAccountTransfer(value: unknown): boolean
 }
 
 export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.post("/v1/workspaces/:workspaceId/external-members", async (c) => {
+    return c.json(
+      await addExternalWorkspaceMemberForRequest(
+        c,
+        deps,
+        c.req.param("workspaceId"),
+        await c.req.json(),
+      ),
+    );
+  });
   app.get("/v1/access/me", async (c) => {
     return c.json(await requireAccessContext(c, deps));
   });
 
   app.get("/v1/workspaces", async (c) => {
     const context = await requireAccessContext(c, deps);
+    const externalWorkspaces = await listExternalActorWorkspaces(context, deps);
+    if (externalWorkspaces !== null)
+      return c.json(externalWorkspaces.map((workspace) => Workspace.parse(workspace)));
     const accountScopedAuthority = accountScopedApiKeyWorkspaceAuthority(context);
     if (
       accountScopedAuthority &&
@@ -243,6 +258,7 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     requireAccountPermission(context, payload.accountId, "workspace:create");
     try {
       const existing = await findWorkspaceByExternalIdentity(deps.db, {
+        accountId: payload.accountId,
         externalSource: payload.externalSource,
         externalId: payload.externalId,
       });

package/src/sandbox/rematerialize.ts

@@ -32,7 +32,11 @@ import {
   type EstablishedSandboxSession,
   type WorkspaceArchiveDescriptor,
 } from "@opengeni/runtime/sandbox";
-import type { ObjectStorage } from "@opengeni/storage";
+import {
+  downloadWorkspaceArchiveSpool,
+  WorkspaceArchiveStorageError,
+  type ObjectStorage,
+} from "@opengeni/storage";
 
 function hasWorkspaceArchive(envelope: Record<string, unknown> | null): boolean {
   const sessionState =
@@ -73,6 +77,14 @@ async function materializeArchiveObjectRef(
       "workspace archive object storage is not configured",
     );
   }
+  const descriptor = parseWorkspaceArchiveDescriptor(sessionState.workspaceArchiveMeta);
+  if (
+    process.platform === "linux" &&
+    descriptor?.version === 1 &&
+    descriptor.workspace.projection === "sdk_local_archive_v1"
+  ) {
+    return envelope;
+  }
   return {
     ...envelope,
     sessionState: await inlineWorkspaceArchiveForRestore(sessionState, (key) =>
@@ -209,6 +221,26 @@ export async function establishApiSandboxSpawner(input: {
     established = await establishSandboxSessionFromEnvelope(input.settings, hydrateEnvelope, {
       sessionId: input.sessionId,
       recovery: "create-or-restore",
+      ...(input.objectStorage
+        ? {
+            loadHostWorkspaceArchive: async (ref) => {
+              try {
+                return await downloadWorkspaceArchiveSpool(input.objectStorage!, ref.key, {
+                  bytes: ref.bytes,
+                  sha256: ref.sha256,
+                });
+              } catch (error) {
+                if (error instanceof WorkspaceArchiveStorageError) {
+                  throw new WorkspaceArchiveIntegrityError(error.code, error.message, {
+                    retryable: error.retryable,
+                    cause: error,
+                  });
+                }
+                throw error;
+              }
+            },
+          }
+        : {}),
       backendOverride: input.backend as never,
       environment: input.environment,
       onSandboxCreated: async (created) => {