@opengeni/api-router 2.5.0 → 2.6.3-canary.0

package/src/routes/workspaces.ts

@@ -1,6 +1,9 @@
 import {
   AddWorkspaceMemberRequest,
   CreateWorkspaceRequest,
+  EnsureWorkspaceRequest,
+  EnsureWorkspaceResponse,
+  ListWorkspaceMemberCandidatesResponse,
   ListWorkspaceMembersResponse,
   SetWorkspaceDefaultRigRequest,
   UpdateWorkspaceMemberRequest,
@@ -16,36 +19,46 @@ import {
   workspaceControlUtf8Bytes,
   type AccessContext,
   type Permission,
+  type WorkspaceMemberCandidate,
   type WorkspaceMember as WorkspaceMemberValue,
 } from "@opengeni/contracts";
 import {
   allWorkspacePermissions,
   createWorkspace,
   deleteWorkspaceIfQuiescent,
-  getManagedUserByEmail,
+  ensureWorkspaceByExternalIdentity,
+  findWorkspaceByExternalIdentity,
+  getManagedUserProfilesByIds,
   getWorkspaceModelPolicy,
   grantWorkspaceAccess,
   listWorkspaceMembers,
+  listWorkspaceMemberManagementCandidates,
   normalizeWorkspaceMembershipPermissions,
   listWorkspaceControlEvents,
+  listSharedWorkspacesForAccount,
   listWorkspacesForSubject,
+  nestedPostgresSqlState,
   removeWorkspaceMember,
   requireWorkspace,
   getRig,
   setWorkspaceDefaultRig,
   updateWorkspace,
   updateWorkspaceSettings,
+  upsertWorkspaceMemberAsWorkspaceManager,
   upsertWorkspaceModelPolicy,
   workspaceCodexSubscriptionActive,
   workspaceControlRequestLockTimeoutMs,
   workspaceXaiSubscriptionActive,
   workspaceVercelAiGatewayConnectionActive,
+  WorkspaceExternalIdentityConflictError,
+  WorkspaceLimitExceededError,
 } from "@opengeni/db";
 import { boundWorkspaceControlHttpPage } from "@opengeni/events";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
   getManagedAuthRequestActorEpoch,
+  accountScopedApiKeyWorkspaceAuthority,
   hasPermission,
   requireAccessContext,
   requireAccessGrant,
@@ -55,19 +68,21 @@ import { requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   assertWorkspaceMemberRemovable,
+  assertWorkspaceMemberUpdateAllowed,
   controlHumanWorkspace,
-  resolveMemberSubjectId,
 } from "@opengeni/core";
 import { boundedLimit } from "../http/common";
 import { ApiHttpError } from "../http/api-error";
-import { sseWorkspaceControlStream } from "../http/sse";
+import { browserSseDeliveryOptions, sseWorkspaceControlStream } from "../http/sse";
 import { buildWorkspaceModelCatalog } from "../model-catalog";
 import { processTemporalScheduleCleanupClaims } from "../temporal-schedule-cleanup";
+import { workspaceDeleteObserver } from "../workspace-delete-observability";
 import {
   AI_GATEWAY_REALTIME_MODELS,
   CODEX_REALTIME_MODEL_ID,
   SUPERGROK_REALTIME_MODEL_ID,
   canonicalizeConfiguredModelId,
+  configuredStaticUsageLimits,
   type Settings,
 } from "@opengeni/config";
 
@@ -114,6 +129,17 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces", async (c) => {
     const context = await requireAccessContext(c, deps);
+    const accountScopedAuthority = accountScopedApiKeyWorkspaceAuthority(context);
+    if (
+      accountScopedAuthority &&
+      hasPermission(accountScopedAuthority.permissions, "workspace:read")
+    ) {
+      return c.json(
+        (await listSharedWorkspacesForAccount(deps.db, accountScopedAuthority.accountId)).map(
+          (workspace) => Workspace.parse(workspace),
+        ),
+      );
+    }
     const readableWorkspaceIds = [
       ...new Set(
         context.workspaceGrants
@@ -134,34 +160,101 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  app.put("/v1/workspaces/external", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const payload = EnsureWorkspaceRequest.parse(await c.req.json());
+    requireAccountPermission(context, payload.accountId, "workspace:create");
+    try {
+      const existing = await findWorkspaceByExternalIdentity(deps.db, {
+        externalSource: payload.externalSource,
+        externalId: payload.externalId,
+      });
+      if (existing) {
+        if (existing.accountId !== payload.accountId || existing.kind !== "shared") {
+          throw new WorkspaceExternalIdentityConflictError();
+        }
+        return c.json(
+          EnsureWorkspaceResponse.parse({
+            workspace: existing,
+            created: false,
+          }),
+        );
+      }
+      await requireLimit(deps, {
+        accountId: payload.accountId,
+        action: "workspace:create",
+        quantity: 1,
+      });
+      const result = await ensureWorkspaceByExternalIdentity(deps.db, {
+        accountId: payload.accountId,
+        externalSource: payload.externalSource,
+        externalId: payload.externalId,
+        name: payload.name,
+        slug: payload.slug ?? null,
+        ...(payload.agentInstructions !== undefined
+          ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
+          : {}),
+        maxWorkspacesPerAccount: workspaceLimit(deps),
+      });
+      const response = EnsureWorkspaceResponse.parse(result);
+      return result.created ? c.json(response, 201) : c.json(response);
+    } catch (error) {
+      if (error instanceof WorkspaceExternalIdentityConflictError) {
+        throw new HTTPException(409, {
+          message: "external workspace identity is already in use",
+        });
+      }
+      if (error instanceof WorkspaceLimitExceededError) {
+        throw new HTTPException(429, { message: error.message });
+      }
+      throw error;
+    }
+  });
+
   app.post("/v1/workspaces", async (c) => {
     const context = await requireAccessContext(c, deps);
     const payload = CreateWorkspaceRequest.parse(await c.req.json());
     const accountId = payload.accountId ?? context.defaultAccountId;
     if (!accountId) {
-      throw new HTTPException(409, { message: "account selection is required" });
+      throw new HTTPException(409, {
+        message: "account selection is required",
+      });
     }
     requireAccountPermission(context, accountId, "workspace:create");
-    await requireLimit(deps, { accountId, action: "workspace:create", quantity: 1 });
-    const workspace = await createWorkspace(deps.db, {
+    await requireLimit(deps, {
       accountId,
-      name: payload.name.trim(),
-      slug: payload.slug?.trim() || null,
-      externalSource: payload.externalSource ?? null,
-      externalId: payload.externalId ?? null,
-      ...(payload.agentInstructions !== undefined
-        ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
-        : {}),
+      action: "workspace:create",
+      quantity: 1,
     });
-    await grantWorkspaceAccess(deps.db, {
-      accountId,
-      workspaceId: workspace.id,
-      subjectId: context.subjectId,
-      role: "owner",
-      permissions: allWorkspacePermissions,
-      ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
-    });
-    return c.json(Workspace.parse(workspace), 201);
+    try {
+      const workspace = await createWorkspace(deps.db, {
+        accountId,
+        name: payload.name.trim(),
+        slug: payload.slug?.trim() || null,
+        externalSource: payload.externalSource ?? null,
+        externalId: payload.externalId ?? null,
+        ...(payload.agentInstructions !== undefined
+          ? {
+              agentInstructions: normalizeAgentInstructions(payload.agentInstructions),
+            }
+          : {}),
+        maxWorkspacesPerAccount: workspaceLimit(deps),
+      });
+      await grantWorkspaceAccess(deps.db, {
+        accountId,
+        workspaceId: workspace.id,
+        subjectId: context.subjectId,
+        role: "owner",
+        permissions: allWorkspacePermissions,
+        ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
+      });
+      return c.json(Workspace.parse(workspace), 201);
+    } catch (error) {
+      if (error instanceof WorkspaceLimitExceededError) {
+        throw new HTTPException(429, { message: error.message });
+      }
+      throw error;
+    }
   });
 
   app.get("/v1/workspaces/:workspaceId", async (c) => {
@@ -189,7 +282,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       ...(payload.name !== undefined ? { name: payload.name.trim() } : {}),
       ...(payload.slug !== undefined ? { slug: payload.slug?.trim() || null } : {}),
       ...(payload.agentInstructions !== undefined
-        ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
+        ? {
+            agentInstructions: normalizeAgentInstructions(payload.agentInstructions),
+          }
         : {}),
     });
     return c.json(Workspace.parse(workspace));
@@ -202,7 +297,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const parsed = UpdateWorkspaceSettingsRequest.safeParse(await c.req.json());
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid workspace settings patch" });
+      throw new HTTPException(400, {
+        message: "invalid workspace settings patch",
+      });
     }
     // Request-scoped: bound the exclusive control-prefix wait so a busy
     // workspace yields the retryable 503 instead of parking this request.
@@ -333,11 +430,15 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     if (workspaceControlUtf8Bytes(grant.subjectId) > WORKSPACE_CONTROL_ACTOR_MAX_BYTES) {
-      throw new HTTPException(400, { message: "workspace-control actor is too large" });
+      throw new HTTPException(400, {
+        message: "workspace-control actor is too large",
+      });
     }
     const parsed = WorkspaceInferenceControlRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid workspace inference-control request" });
+      throw new HTTPException(400, {
+        message: "invalid workspace inference-control request",
+      });
     }
     return c.json(
       await controlHumanWorkspace(
@@ -383,6 +484,7 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       after,
       c.req.raw.signal,
       {
+        ...browserSseDeliveryOptions(c.req.query("transport")),
         observability: deps.observability,
         actorEpoch: getManagedAuthRequestActorEpoch(c.req.raw) ?? undefined,
         reauthorize: async () => {
@@ -399,7 +501,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (payload.rigId) {
       const rig = await getRig(deps.db, workspaceId, payload.rigId);
       if (!rig) {
-        throw new HTTPException(422, { message: `unknown rigId: ${payload.rigId}` });
+        throw new HTTPException(422, {
+          message: `unknown rigId: ${payload.rigId}`,
+        });
       }
     }
     const workspace = await setWorkspaceDefaultRig(deps.db, workspaceId, payload.rigId);
@@ -413,15 +517,22 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     // session/lease before checking runtime quiescence, then returns the exact
     // external schedules removed by the cascade. A racing cold->warm transition
     // can therefore never erase the only provider/capture ownership receipt.
+    const deleteObserver = workspaceDeleteObserver(deps.observability, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
     const deleted = await deleteWorkspaceIfQuiescent(deps.db, {
       accountId: grant.accountId,
       workspaceId,
+      ...(deleteObserver ? { observer: deleteObserver } : {}),
     });
     if (deleted.status === "not_found") {
       throw new HTTPException(404, { message: "workspace not found" });
     }
     if (deleted.status === "only_workspace") {
-      throw new HTTPException(409, { message: "cannot delete the account's only workspace" });
+      throw new HTTPException(409, {
+        message: "cannot delete the account's only workspace",
+      });
     }
     if (deleted.status === "active_sessions") {
       throw new HTTPException(409, {
@@ -453,7 +564,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       {
         db: deps.db,
         deleteSchedule: async (temporalScheduleId) => {
-          await deps.workflowClient.deleteScheduledTaskSchedule({ temporalScheduleId });
+          await deps.workflowClient.deleteScheduledTaskSchedule({
+            temporalScheduleId,
+          });
         },
         ...(deps.observability ? { observability: deps.observability } : {}),
       },
@@ -467,28 +580,73 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/members", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    const members = await listWorkspacePeople(deps, workspaceId);
     return c.json(workspaceMembersResponse(members));
   });
 
+  app.get("/v1/workspaces/:workspaceId/member-candidates", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
+    try {
+      return c.json(
+        ListWorkspaceMemberCandidatesResponse.parse({
+          members: await listWorkspaceMemberManagementCandidates(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            actorSubjectId: grant.subjectId,
+          }),
+        }),
+      );
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+  });
+
   app.post("/v1/workspaces/:workspaceId/members", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
     const payload = AddWorkspaceMemberRequest.parse(await c.req.json());
-    const email = payload.email.trim();
-    // Email invites for not-yet-registered users are deferred: an unknown email
-    // resolves to null, which resolveMemberSubjectId turns into a 404.
-    const subjectId = resolveMemberSubjectId(await getManagedUserByEmail(deps.db, email));
-    await grantWorkspaceAccess(deps.db, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId,
-      subjectLabel: email,
-      ...(payload.role !== undefined ? { role: payload.role } : {}),
-      permissions: payload.permissions,
-    });
-    const members = await listWorkspaceMembers(deps.db, workspaceId);
-    const member = members.find((candidate) => candidate.subjectId === subjectId);
+    let candidates: WorkspaceMemberCandidate[];
+    try {
+      candidates = await listWorkspaceMemberManagementCandidates(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+      });
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+    const candidate = candidates.find(
+      (entry) => entry.organizationMembershipId === payload.organizationMembershipId,
+    );
+    if (!candidate) {
+      throw new HTTPException(404, {
+        message: "this organization member is not available to add",
+      });
+    }
+    const subjectId = candidate.subjectId;
+    const existing = await listWorkspaceMembers(deps.db, workspaceId);
+    if (existing.some((member) => member.subjectId === subjectId)) {
+      throw new HTTPException(409, {
+        message: "this person already has access to the workspace",
+      });
+    }
+    try {
+      await upsertWorkspaceMemberAsWorkspaceManager(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+        targetSubjectId: subjectId,
+        mode: "add",
+        subjectLabel: candidate.name?.trim() || candidate.email || subjectId,
+        role: payload.role ?? "member",
+        permissions: payload.permissions,
+      });
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+    const members = await listWorkspacePeople(deps, workspaceId);
+    const member = members.find((addedMember) => addedMember.subjectId === subjectId);
     if (!member) {
       throw new HTTPException(500, { message: "failed to add member" });
     }
@@ -500,20 +658,32 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
     const subjectId = decodeURIComponent(c.req.param("subjectId"));
     const payload = UpdateWorkspaceMemberRequest.parse(await c.req.json());
-    const existing = await listWorkspaceMembers(deps.db, workspaceId);
+    const existing = await listWorkspacePeople(deps, workspaceId);
     const current = existing.find((member) => member.subjectId === subjectId);
     if (!current) {
       throw new HTTPException(404, { message: "member not found" });
     }
-    await grantWorkspaceAccess(deps.db, {
-      accountId: grant.accountId,
-      workspaceId,
+    assertWorkspaceMemberUpdateAllowed({
+      members: existing,
       subjectId,
-      ...(current.subjectLabel ? { subjectLabel: current.subjectLabel } : {}),
-      role: payload.role ?? current.role,
-      permissions: payload.permissions,
+      callerSubjectId: grant.subjectId,
+      nextPermissions: payload.permissions,
     });
-    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    try {
+      await upsertWorkspaceMemberAsWorkspaceManager(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        actorSubjectId: grant.subjectId,
+        targetSubjectId: subjectId,
+        mode: "update",
+        ...(current.subjectLabel ? { subjectLabel: current.subjectLabel } : {}),
+        role: payload.role ?? current.role,
+        permissions: payload.permissions,
+      });
+    } catch (error) {
+      rethrowWorkspaceMemberCandidateError(error);
+    }
+    const members = await listWorkspacePeople(deps, workspaceId);
     const member = members.find((candidate) => candidate.subjectId === subjectId);
     if (!member) {
       throw new HTTPException(500, { message: "failed to update member" });
@@ -528,7 +698,11 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const members = await listWorkspaceMembers(deps.db, workspaceId);
     // Never remove yourself, and never remove the last administering member.
     // The fenced removal command re-enforces both guards fail-closed.
-    assertWorkspaceMemberRemovable({ members, subjectId, callerSubjectId: grant.subjectId });
+    assertWorkspaceMemberRemovable({
+      members,
+      subjectId,
+      callerSubjectId: grant.subjectId,
+    });
     await removeWorkspaceMember(deps.db, {
       accountId: grant.accountId,
       workspaceId,
@@ -539,6 +713,69 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
+function workspaceLimit(deps: ApiRouteDeps): number | null {
+  if (deps.settings.usageLimitsMode !== "static" && deps.settings.usageLimitsMode !== "managed") {
+    return null;
+  }
+  return configuredStaticUsageLimits(deps.settings).maxWorkspacesPerAccount ?? null;
+}
+
+async function listWorkspacePeople(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+): Promise<WorkspaceMemberValue[]> {
+  const members = await listWorkspaceMembers(deps.db, workspaceId);
+  const userIds = members.flatMap((member) =>
+    member.subjectId.startsWith("user:") ? [member.subjectId.slice("user:".length)] : [],
+  );
+  const profiles = await getManagedUserProfilesByIds(deps.db, userIds);
+  const profileBySubject = new Map(
+    profiles.map((profile) => [`user:${profile.id}`, profile.name?.trim() || profile.email]),
+  );
+  return members.map((member) => ({
+    ...member,
+    subjectLabel: profileBySubject.get(member.subjectId) ?? member.subjectLabel,
+  }));
+}
+
+function rethrowWorkspaceMemberCandidateError(error: unknown): never {
+  const managementCode =
+    error && typeof error === "object" && "code" in error ? error.code : undefined;
+  if (managementCode === "WORKSPACE_MEMBER_ALREADY_EXISTS") {
+    throw new HTTPException(409, {
+      message: "this person already has access to the workspace",
+    });
+  }
+  if (managementCode === "WORKSPACE_MEMBER_NOT_FOUND") {
+    throw new HTTPException(404, { message: "member not found" });
+  }
+  if (managementCode === "WORKSPACE_MEMBER_SELF_UPDATE") {
+    throw new HTTPException(409, {
+      message: "you cannot change your own workspace access",
+    });
+  }
+  if (managementCode === "WORKSPACE_MEMBER_LAST_ADMIN") {
+    throw new HTTPException(409, {
+      message: "the workspace must keep at least one administrator",
+    });
+  }
+  const sqlState = nestedPostgresSqlState(error);
+  if (sqlState === "P0002") {
+    throw new HTTPException(404, { message: "workspace not found" });
+  }
+  if (sqlState === "42501") {
+    throw new HTTPException(403, {
+      message: "workspace member management is not allowed",
+    });
+  }
+  if (sqlState === "54000") {
+    throw new HTTPException(409, {
+      message: "this organization has too many members to show here",
+    });
+  }
+  throw error;
+}
+
 // A persona override that is null or trims to empty collapses to null (use the
 // deployment default). Otherwise the template is stored verbatim so the runtime
 // can substitute the non-bypassable CORE at its {{core}} marker.
@@ -560,6 +797,8 @@ function requireAccountPermission(
     !grant ||
     (!grant.permissions.includes(permission) && !grant.permissions.includes("account:admin"))
   ) {
-    throw new HTTPException(403, { message: `missing permission: ${permission}` });
+    throw new HTTPException(403, {
+      message: `missing permission: ${permission}`,
+    });
   }
 }

package/src/sandbox/channel-a.ts

@@ -86,6 +86,8 @@ import {
   type RoutingSandboxSession,
 } from "@opengeni/runtime/sandbox";
 import {
+  managedSessionGroupBackend,
+  managedSessionGroupOs,
   providerSettingsForSessionSandboxRuntime,
   relayConfigFromSettings,
   resolveSessionSandboxRuntime,
@@ -643,15 +645,19 @@ async function withChannelAOperation<T>(
         // A machine-home session with no selected machine uses the deployment's
         // managed group box, exactly like the worker turn path. Keep the durable
         // home label honest; only this request's effective backend changes.
-        if (settings.sandboxBackend !== "none" && settings.sandboxBackend !== "selfhosted") {
+        const groupBackend = managedSessionGroupBackend(
+          settings.sandboxBackend,
+          session.sandboxBackend,
+        );
+        if (groupBackend) {
           return await withChannelAOperation(
             services,
             {
               ...ctx,
               session: {
                 ...session,
-                sandboxBackend: settings.sandboxBackend,
-                sandboxOs: "linux",
+                sandboxBackend: groupBackend,
+                sandboxOs: managedSessionGroupOs(session.sandboxBackend, session.sandboxOs),
               },
             },
             readOnly,
@@ -659,7 +665,7 @@ async function withChannelAOperation<T>(
           );
         }
         throw new HTTPException(409, {
-          message: "machine-home session has no active Connected Machine",
+          message: "machine-home session has no active Connected Machine or managed sandbox",
         });
       }
       const sandbox = await getSandbox(

package/src/sandbox/machines.ts

@@ -9,8 +9,9 @@
 //     heartbeat), projected to the contract's MetricSample;
 //   * sharedSessionCount — the lease refcount (how many sessions share this one
 //     whole machine, the maxSandboxes:1 disclosure).
-// PLUS, when a session context is supplied, the session's synthetic Modal group
-// box (isSessionGroup:true) + the active-sandbox pointer (activeSandboxId/Epoch).
+// PLUS, when a session context is supplied, the session's synthetic managed
+// group box (isSessionGroup:true) + the active-sandbox pointer
+// (activeSandboxId/Epoch).
 //
 // This is workspace-scoped (perm enrollments:read) and flag-gated upstream
 // (sandboxSelfhostedEnabled). It deliberately does NOT depend on a FleetContext
@@ -32,6 +33,7 @@ import {
   type MachineMetricsRow,
 } from "@opengeni/db";
 import { MachineView, MetricSample, type MachinesResponse } from "@opengeni/contracts";
+import { managedSessionGroupBackend } from "@opengeni/core";
 import { selfhostedHeartbeatLiveness } from "@opengeni/runtime/sandbox";
 
 export type MachinesServices = {
@@ -244,10 +246,15 @@ export async function listMachines(
   }
 
   const machines: MachineView[] = [];
+  const groupBackend = session
+    ? managedSessionGroupBackend(services.settings.sandboxBackend, session.sandboxBackend)
+    : null;
 
-  // The session's own group box (synthetic): the default/home sandbox a null
-  // active pointer routes to. A backend:none session has no home box.
-  if (session && session.sandboxBackend !== "none") {
+  // The session's own managed group box (synthetic): the sandbox a null active
+  // pointer routes to. A machine-home session uses the deployment's managed
+  // backend only after an explicit switch; none/selfhosted-only deployments do
+  // not invent a group they cannot establish.
+  if (session && groupBackend) {
     const groupActive = activeSandboxId === null;
     const groupLease = await readLease(db, workspaceId, session.sandboxGroupId);
     machines.push(
@@ -255,7 +262,7 @@ export async function listMachines(
         sandboxId: session.sandboxGroupId,
         enrollmentId: null,
         name: "session sandbox",
-        kind: session.sandboxBackend === "selfhosted" ? "selfhosted" : "modal",
+        kind: groupBackend === "opensandbox" ? "opensandbox" : "modal",
         state: "online",
         active: groupActive,
         isSessionGroup: true,