@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/workspaces.ts

@@ -1,65 +1,148 @@
+import { withDirectModelProviders } from "@opengeni/config";
+import { listConnectionsMetadata } from "@opengeni/db";
+import {
+  workspaceProviderApiKeyConnectionMetadataFromConnections,
+  listWorkspaceProviderCustomModelsByKind,
+  getOrganizationModelProviderCatalogForWorkspace,
+  type WorkspaceCustomModelProviderKind,
+} from "@opengeni/db";
+import { CLAUDE_CONNECTION_KINDS, type ClaudeConnectionCatalog } from "@opengeni/config";
+import { SessionControlConflictError, WorkspacePauseTimerInputError } from "@opengeni/db";
+import { updateWorkspaceSettingsWithToolDefaults } from "@opengeni/db/workspace-tool-defaults";
+import { WorkspacePauseTimerRequest } from "@opengeni/contracts";
+import { getWorkspaceConnectionModelRestrictions } from "@opengeni/db";
+import { createHash } from "node:crypto";
 import {
   AddWorkspaceMemberRequest,
   CreateWorkspaceRequest,
+  EnsureWorkspaceRequest,
+  EnsureWorkspaceResponse,
+  ListWorkspaceMemberCandidatesResponse,
   ListWorkspaceMembersResponse,
   SetWorkspaceDefaultRigRequest,
   UpdateWorkspaceMemberRequest,
+  CreateWorkspaceGatewayCustomModelRequest,
+  CreateWorkspaceOpenRouterCustomModelRequest,
+  DeleteWorkspaceGatewayCustomModelRequest,
+  DeleteWorkspaceOpenRouterCustomModelRequest,
   UpdateWorkspaceModelPolicyRequest,
   UpdateWorkspaceRequest,
   UpdateWorkspaceSettingsRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   WorkspaceModelCatalogResponse,
+  WorkspaceGatewayCustomModel,
+  WorkspaceGatewayCustomModelsResponse,
+  WorkspaceOpenRouterCustomModel,
+  WorkspaceOpenRouterCustomModelsResponse,
   WorkspaceRealtimeModelCatalogResponse,
   WorkspaceInferenceControlRequest,
   Workspace,
   WorkspaceMember,
   workspaceControlUtf8Bytes,
+  stableJson,
   type AccessContext,
   type Permission,
+  type WorkspaceMemberCandidate,
+  type WorkspaceMember as WorkspaceMemberValue,
 } from "@opengeni/contracts";
+import { loadWorkspaceCodexModelAvailability } from "@opengeni/core";
 import {
   allWorkspacePermissions,
   createWorkspace,
-  deleteWorkspaceIfQuiescent,
-  getManagedUserByEmail,
+  ensureWorkspaceByExternalIdentity,
+  findWorkspaceByExternalIdentity,
+  getManagedUserProfilesByIds,
+  getWorkspace,
   getWorkspaceModelPolicy,
   grantWorkspaceAccess,
   listWorkspaceMembers,
+  listWorkspaceMemberManagementCandidates,
+  normalizeWorkspaceMembershipPermissions,
   listWorkspaceControlEvents,
+  listSharedWorkspacesForAccount,
+  listWorkspaceGatewayCustomModels,
+  listWorkspaceOpenRouterCustomModels,
+  createWorkspaceGatewayCustomModel,
+  createWorkspaceOpenRouterCustomModel,
+  deleteWorkspaceGatewayCustomModel,
+  deleteWorkspaceOpenRouterCustomModel,
+  replayWorkspaceGatewayCustomModelCreate,
+  replayWorkspaceOpenRouterCustomModelCreate,
   listWorkspacesForSubject,
+  nestedPostgresSqlState,
   removeWorkspaceMember,
   requireWorkspace,
+  updateWorkspaceSettings,
   getRig,
   setWorkspaceDefaultRig,
   updateWorkspace,
-  updateWorkspaceSettings,
+  upsertWorkspaceMemberAsWorkspaceManager,
   upsertWorkspaceModelPolicy,
   workspaceCodexSubscriptionActive,
+  workspaceControlRequestLockTimeoutMs,
   workspaceXaiSubscriptionActive,
   workspaceVercelAiGatewayConnectionActive,
+  WorkspaceGatewayCustomModelHistoryLimitError,
+  WorkspaceOpenRouterCustomModelHistoryLimitError,
+  WorkspaceExternalIdentityConflictError,
+  WorkspaceGatewayCustomModelLimitError,
+  WorkspaceOpenRouterCustomModelLimitError,
+  WorkspaceLimitExceededError,
 } from "@opengeni/db";
 import { boundWorkspaceControlHttpPage } from "@opengeni/events";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { hasPermission, requireAccessContext, requireAccessGrant } from "@opengeni/core";
+import {
+  getManagedAuthRequestActorEpoch,
+  accountScopedApiKeyWorkspaceAuthority,
+  organizationWorkspaceInScope,
+  hasPermission,
+  requireAccessContext,
+  requireApiKeyDelegationContext,
+  requireExplicitPermissionDelegation,
+  isDeveloperSetupApiKeyContext,
+  listExternalActorWorkspaces,
+  addExternalWorkspaceMemberForRequest,
+  requireAccessGrant,
+  requireWorkspaceSettingsGrant,
+  requireFreshAccessGrant,
+  resolveWorkspaceCatalogSettings,
+  creditsDefaultSessionModel,
+  loadWorkspaceClaudeSubscriptionReadiness,
+  resolveDefaultSessionModelForSelections,
+  resolveWorkspaceModelSelection,
+} from "@opengeni/core";
 import { requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   assertWorkspaceMemberRemovable,
+  assertWorkspaceMemberUpdateAllowed,
   controlHumanWorkspace,
-  resolveMemberSubjectId,
+  controlHumanWorkspaceTimer,
 } from "@opengeni/core";
 import { boundedLimit } from "../http/common";
-import { sseWorkspaceControlStream } from "../http/sse";
-import { buildWorkspaceModelCatalog } from "../model-catalog";
-import { processTemporalScheduleCleanupClaims } from "../temporal-schedule-cleanup";
+import { ApiHttpError } from "../http/api-error";
+import { browserSseDeliveryOptions, sseWorkspaceControlStream } from "../http/sse";
+import { projectWorkspaceModelCatalog } from "../model-catalog";
+import { deleteWorkspaceForRequest } from "../workspace-deletion";
 import {
   AI_GATEWAY_REALTIME_MODELS,
   CODEX_REALTIME_MODEL_ID,
   SUPERGROK_REALTIME_MODEL_ID,
   canonicalizeConfiguredModelId,
+  configuredStaticUsageLimits,
+  configuredGatewayUpstreamModelIds,
+  configuredGatewayWorkspaceProductModelIds,
+  configuredModelInputIdentities,
+  configuredOpenRouterUpstreamModelIds,
+  configuredOpenRouterWorkspaceProductModelIds,
+  WORKSPACE_GATEWAY_MODEL_ID_PREFIX,
+  WORKSPACE_OPENROUTER_MODEL_ID_PREFIX,
+  sandboxImageAllowlist,
   type Settings,
 } from "@opengeni/config";
+import { AddExternalWorkspaceMemberRequest } from "@opengeni/contracts/external-identities";
+import { parseRequestBody, parseRequestJson, readRequestJson } from "../http/request-body";
 
 export function canonicalWorkspacePolicyModelIds(
   settings: Settings,
@@ -71,13 +154,145 @@ export function canonicalWorkspacePolicyModelIds(
   return [...new Set(modelIds.map((modelId) => canonicalizeConfiguredModelId(settings, modelId)))];
 }
 
+function projectWorkspaceGatewayCustomModel(model: {
+  id: string;
+  upstreamModelId: string;
+  label: string | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}) {
+  return WorkspaceGatewayCustomModel.parse({
+    id: model.id,
+    upstreamModelId: model.upstreamModelId,
+    label: model.label,
+    version: model.version,
+    createdAt: model.createdAt.toISOString(),
+    updatedAt: model.updatedAt.toISOString(),
+  });
+}
+
+function projectWorkspaceOpenRouterCustomModel(model: {
+  id: string;
+  upstreamModelId: string;
+  label: string | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}) {
+  return WorkspaceOpenRouterCustomModel.parse({
+    id: model.id,
+    upstreamModelId: model.upstreamModelId,
+    label: model.label,
+    version: model.version,
+    createdAt: model.createdAt.toISOString(),
+    updatedAt: model.updatedAt.toISOString(),
+  });
+}
+
+function workspaceCustomModelRequestHash(value: unknown): string {
+  return createHash("sha256").update(stableJson(value), "utf8").digest("hex");
+}
+
+type WorkspaceMemberProjectionInput = Omit<WorkspaceMemberValue, "permissions"> & {
+  permissions: unknown;
+};
+
+/**
+ * Keep the roster readable across stored-permission contract changes. Unknown
+ * values are never re-authorized: they are omitted from the public projection,
+ * while every currently recognized permission is preserved in stored order.
+ */
+export function workspaceMembersResponse(members: readonly WorkspaceMemberProjectionInput[]) {
+  return ListWorkspaceMembersResponse.parse({
+    members: members.map((member) => ({
+      ...member,
+      permissions: normalizeWorkspaceMembershipPermissions(member.permissions),
+    })),
+  });
+}
+
+export function workspaceUpdateRequestsSettings(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.prototype.hasOwnProperty.call(value, "settings")
+  );
+}
+
+export function workspaceUpdateRequestsAccountTransfer(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.prototype.hasOwnProperty.call(value, "accountId")
+  );
+}
+
+/**
+ * Owning organization for `PUT /v1/workspaces/external`. An organization API
+ * key can only ever create workspaces in its own organization, so an omitted
+ * `accountId` resolves to that organization. Every other caller - notably a
+ * human who may belong to several organizations - must name it explicitly;
+ * guessing a default there could create the workspace in the wrong tenant.
+ */
+export function externalWorkspaceAccountId(
+  context: AccessContext,
+  requested: string | undefined,
+): string {
+  if (requested !== undefined) return requested;
+  const organizationKey = accountScopedApiKeyWorkspaceAuthority(context);
+  if (organizationKey) return organizationKey.accountId;
+  throw new ApiHttpError(400, {
+    code: "validation_failed",
+    message:
+      "Invalid request body: accountId: required - pass the id of the organization that will own the workspace (only an organization API key may omit it).",
+    retryable: false,
+    details: {
+      code: "invalid_request_body",
+      issues: [{ path: "accountId", message: "Required" }],
+      omittedIssueCount: 0,
+    },
+  });
+}
+
 export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.post("/v1/workspaces/:workspaceId/external-members", async (c) => {
+    // Validate at the HTTP boundary so a malformed body is a 400, not a raw
+    // schema error from the application layer.
+    const body = await readRequestJson(c);
+    parseRequestBody(AddExternalWorkspaceMemberRequest, body);
+    return c.json(
+      await addExternalWorkspaceMemberForRequest(c, deps, c.req.param("workspaceId"), body),
+    );
+  });
   app.get("/v1/access/me", async (c) => {
     return c.json(await requireAccessContext(c, deps));
   });
 
+  app.get("/v1/workspaces/:workspaceId/access/grant", async (c) => {
+    // Inventory may be empty for an external actor. Resolve the selected
+    // workspace through the canonical membership/key-ceiling boundary.
+    const grant = await requireAccessGrant(c, deps, c.req.param("workspaceId"));
+    c.header("cache-control", "private, no-store");
+    return c.json(grant);
+  });
+
   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) {
+      if (!hasPermission(accountScopedAuthority.permissions, "workspace:read")) return c.json([]);
+      return c.json(
+        (await listSharedWorkspacesForAccount(deps.db, accountScopedAuthority.accountId))
+          .filter((workspace) =>
+            organizationWorkspaceInScope(accountScopedAuthority.workspaceScope, workspace.id),
+          )
+          .map((workspace) => Workspace.parse(workspace)),
+      );
+    }
     const readableWorkspaceIds = [
       ...new Set(
         context.workspaceGrants
@@ -98,34 +313,123 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  app.put("/v1/workspaces/external", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const request = await parseRequestJson(c, EnsureWorkspaceRequest);
+    const accountId = externalWorkspaceAccountId(context, request.accountId);
+    const payload = { ...request, accountId };
+    requireAccountPermission(context, accountId, "workspace:create");
+    try {
+      const existing = await findWorkspaceByExternalIdentity(deps.db, {
+        accountId: payload.accountId,
+        externalSource: payload.externalSource,
+        externalId: payload.externalId,
+      });
+      if (existing) {
+        if (existing.accountId !== payload.accountId || existing.kind !== "shared") {
+          throw new WorkspaceExternalIdentityConflictError();
+        }
+        const authority = accountScopedApiKeyWorkspaceAuthority(context);
+        if (authority && !organizationWorkspaceInScope(authority.workspaceScope, existing.id))
+          throw new HTTPException(403, { message: "workspace is outside organization key scope" });
+        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);
+      const authority = accountScopedApiKeyWorkspaceAuthority(context);
+      if (
+        !result.created &&
+        authority &&
+        !organizationWorkspaceInScope(authority.workspaceScope, result.workspace.id)
+      )
+        throw new HTTPException(403, { message: "workspace is outside organization key scope" });
+      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 payload = await parseRequestJson(c, CreateWorkspaceRequest);
     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),
+      });
+      // Setup keys already have canonical same-organization workspace access.
+      // Do not widen that ceiling with an all-permissions creator membership.
+      if (
+        !isDeveloperSetupApiKeyContext(context) &&
+        accountScopedApiKeyWorkspaceAuthority(context)?.permissionMode !== "explicit"
+      ) {
+        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) => {
@@ -137,12 +441,43 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.patch("/v1/workspaces/:workspaceId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-    const payload = UpdateWorkspaceRequest.parse(await c.req.json());
+    const body = await readRequestJson(c);
+    if (workspaceUpdateRequestsSettings(body)) {
+      throw new ApiHttpError(400, {
+        code: "validation_failed",
+        message:
+          "Invalid request body: settings: workspace settings are not accepted here; send them to PATCH /v1/workspaces/:workspaceId/settings (SDK: updateWorkspaceSettings).",
+        retryable: false,
+        details: {
+          code: "invalid_request_body",
+          issues: [
+            {
+              path: "settings",
+              message: "Use PATCH /v1/workspaces/:workspaceId/settings",
+            },
+          ],
+          omittedIssueCount: 0,
+        },
+      });
+    }
+    if (workspaceUpdateRequestsAccountTransfer(body)) {
+      throw new ApiHttpError(409, {
+        code: "conflict",
+        message:
+          "A workspace is permanently owned by one organization; use workspace grants for same-organization access handoff.",
+        retryable: false,
+        outcomeUnknown: false,
+        details: { code: "workspace_transfer_unsupported" },
+      });
+    }
+    const payload = parseRequestBody(UpdateWorkspaceRequest, body);
     const workspace = await updateWorkspace(deps.db, workspaceId, {
       ...(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));
@@ -152,13 +487,42 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   // deep-merges (top-level) a settings patch, preserving unknown/future keys.
   app.patch("/v1/workspaces/:workspaceId/settings", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    await requireWorkspaceSettingsGrant(c, deps, workspaceId);
     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",
+      });
+    }
+    const requestedImage = parsed.data.defaultSandboxImage;
+    if (requestedImage && !sandboxImageAllowlist(deps.settings).includes(requestedImage)) {
+      throw new HTTPException(422, {
+        message:
+          "defaultSandboxImage must be one of the images in this deployment's OPENGENI_SANDBOX_IMAGE_ALLOWLIST",
+      });
+    }
+    // Request-scoped: bound the exclusive control-prefix wait so a busy
+    // workspace yields the retryable 503 instead of parking this request.
+    try {
+      const workspace = await updateWorkspaceSettingsWithToolDefaults(
+        deps.db,
+        workspaceId,
+        parsed.data,
+        { requireWorkspace, updateWorkspaceSettings },
+        {
+          controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
+        },
+      );
+      return c.json(Workspace.parse(workspace));
+    } catch (error) {
+      if (nestedPostgresSqlState(error) === "0A000") {
+        throw new HTTPException(409, {
+          message:
+            "Memory settings moved to Settings > Agent learning. Refresh the app to change them.",
+        });
+      }
+      throw error;
     }
-    const workspace = await updateWorkspaceSettings(deps.db, workspaceId, parsed.data);
-    return c.json(Workspace.parse(workspace));
   });
 
   // Per-workspace model/provider availability policy (the HARD blocker over
@@ -168,31 +532,392 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/model-catalog", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const resolvedCatalog = await deps.resolveCatalogSettings();
+    const providerKinds: WorkspaceCustomModelProviderKind[] = [
+      "vercel_gateway",
+      "openrouter",
+      ...CLAUDE_CONNECTION_KINDS.filter(
+        (kind) =>
+          kind !== "claude_subscription" || resolvedCatalog.settings.claudeSubscriptionEnabled,
+      ),
+    ];
     const [
+      connectionModelRestrictions,
       policy,
       codexSubscriptionActive,
+      codexModelAvailability,
       xaiSubscriptionActive,
-      workspaceGatewayConnectionActive,
+      claudePool,
+      workspaceConnections,
+      workspaceCustomModels,
+      organizationProviders,
+      workspace,
     ] = await Promise.all([
+      getWorkspaceConnectionModelRestrictions(deps.db, workspaceId, grant.subjectId),
       getWorkspaceModelPolicy(deps.db, workspaceId),
       workspaceCodexSubscriptionActive(deps.db, deps.settings, workspaceId),
+      loadWorkspaceCodexModelAvailability(deps.db, resolvedCatalog.settings, workspaceId),
       workspaceXaiSubscriptionActive(deps.db, deps.settings, workspaceId, grant.subjectId),
-      workspaceVercelAiGatewayConnectionActive(deps.db, workspaceId),
+      loadWorkspaceClaudeSubscriptionReadiness(deps.db, resolvedCatalog.settings, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+      }),
+      listConnectionsMetadata(deps.db, workspaceId, null),
+      listWorkspaceProviderCustomModelsByKind(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        providerKinds,
+      }),
+      getOrganizationModelProviderCatalogForWorkspace(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        providerKinds,
+      }),
+      getWorkspace(deps.db, workspaceId),
     ]);
+    const claudeConnections: ClaudeConnectionCatalog = {};
+    const workspaceClaudeConnections: ClaudeConnectionCatalog = {};
+    const workspaceConnectionActive = (kind: WorkspaceCustomModelProviderKind) =>
+      workspaceProviderApiKeyConnectionMetadataFromConnections(workspaceConnections, kind) !== null;
+    for (const kind of CLAUDE_CONNECTION_KINDS) {
+      if (kind === "claude_subscription" && !resolvedCatalog.settings.claudeSubscriptionEnabled)
+        continue;
+      claudeConnections[kind] = {
+        active:
+          kind === "claude_subscription"
+            ? claudePool.organization
+            : organizationProviders[kind].active,
+        models: organizationProviders[kind].models,
+      };
+      workspaceClaudeConnections[kind] = {
+        active:
+          kind === "claude_subscription" ? claudePool.workspace : workspaceConnectionActive(kind),
+        models: workspaceCustomModels[kind],
+      };
+    }
+    const workspaceCatalogSettings = withDirectModelProviders(
+      resolvedCatalog.settings,
+      workspaceConnections,
+    );
+    const selections = resolveWorkspaceModelSelection({
+      claudeConnections,
+      workspaceClaudeConnections,
+      connectionModelRestrictions,
+      settings: workspaceCatalogSettings,
+      policy,
+      observations: codexModelAvailability,
+      codexSubscriptionActive,
+      xaiSubscriptionActive,
+      workspaceGatewayConnectionActive: workspaceConnectionActive("vercel_gateway"),
+      workspaceGatewayCustomModels: workspaceCustomModels.vercel_gateway,
+      workspaceOpenRouterConnectionActive: workspaceConnectionActive("openrouter"),
+      workspaceOpenRouterCustomModels: workspaceCustomModels.openrouter,
+      organizationGatewayConnectionActive: organizationProviders.vercel_gateway.active,
+      organizationOpenRouterConnectionActive: organizationProviders.openrouter.active,
+      organizationGatewayCustomModels: organizationProviders.vercel_gateway.models,
+      organizationOpenRouterCustomModels: organizationProviders.openrouter.models,
+    });
+    // The same precedence the server applies when a new chat, API create, or
+    // scheduled occurrence names no model; published so pickers show it.
+    const workspaceSettings = workspace?.settings ?? {};
+    const defaultSelection = await resolveDefaultSessionModelForSelections(deps.db, {
+      settings: workspaceCatalogSettings,
+      accountId: grant.accountId,
+      workspaceSettings,
+      selections,
+    });
     c.header("cache-control", "private, no-store");
     return c.json(
       WorkspaceModelCatalogResponse.parse(
-        buildWorkspaceModelCatalog({
-          settings: deps.settings,
-          policy,
-          codexSubscriptionActive,
-          xaiSubscriptionActive,
-          workspaceGatewayConnectionActive,
+        projectWorkspaceModelCatalog(selections, {
+          defaultSelection,
+          creditsSelection: creditsDefaultSessionModel({
+            settings: workspaceCatalogSettings,
+            selections,
+            workspaceSettings,
+          }),
         }),
       ),
     );
   });
 
+  app.get("/v1/workspaces/:workspaceId/gateway-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const models = await listWorkspaceGatewayCustomModels(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      WorkspaceGatewayCustomModelsResponse.parse({
+        models: models.map(projectWorkspaceGatewayCustomModel),
+      }),
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/gateway-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
+    const parsed = CreateWorkspaceGatewayCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid Gateway custom model" });
+    }
+    const requestHash = workspaceCustomModelRequestHash({
+      action: "create",
+      upstreamModelId: parsed.data.upstreamModelId,
+      label: parsed.data.label ?? null,
+    });
+    const replay = await replayWorkspaceGatewayCustomModelCreate(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      operationId: parsed.data.operationId,
+      requestHash,
+    });
+    if (replay.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "Gateway custom model operation conflicts with current state",
+      });
+    }
+    if (replay.outcome === "success") {
+      return c.json(projectWorkspaceGatewayCustomModel(replay.model), 201);
+    }
+    const catalog = await deps.resolveCatalogSettings();
+    if (configuredGatewayUpstreamModelIds(catalog.settings).includes(parsed.data.upstreamModelId)) {
+      throw new HTTPException(422, {
+        message: "Gateway model is already included in the deployment catalog",
+      });
+    }
+    const customProductId = `${WORKSPACE_GATEWAY_MODEL_ID_PREFIX}${parsed.data.upstreamModelId}`;
+    const deploymentProductIds = new Set([
+      ...configuredModelInputIdentities(catalog.settings),
+      ...configuredGatewayWorkspaceProductModelIds(catalog.settings),
+    ]);
+    if (deploymentProductIds.has(customProductId)) {
+      throw new HTTPException(422, {
+        message: "Gateway model product id conflicts with the deployment catalog",
+      });
+    }
+    try {
+      const model = await createWorkspaceGatewayCustomModel(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        upstreamModelId: parsed.data.upstreamModelId,
+        label: parsed.data.label ?? null,
+        operationId: parsed.data.operationId,
+        requestHash,
+        createdBySubjectId: grant.subjectId,
+      });
+      if (!model || model.retiredAt) {
+        throw new HTTPException(409, {
+          message: "Gateway custom model operation conflicts with current state",
+        });
+      }
+      return c.json(projectWorkspaceGatewayCustomModel(model), 201);
+    } catch (error) {
+      if (
+        error instanceof WorkspaceGatewayCustomModelLimitError ||
+        error instanceof WorkspaceGatewayCustomModelHistoryLimitError
+      ) {
+        throw new HTTPException(422, { message: error.message });
+      }
+      if (nestedPostgresSqlState(error) === "23505") {
+        throw new HTTPException(422, {
+          message: "Gateway custom model already exists",
+        });
+      }
+      throw error;
+    }
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/gateway-custom-models/:customModelId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
+    const customModelId = c.req.param("customModelId");
+    if (
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(
+        customModelId,
+      )
+    ) {
+      throw new HTTPException(422, {
+        message: "invalid Gateway custom model id",
+      });
+    }
+    const parsed = DeleteWorkspaceGatewayCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, {
+        message: "invalid Gateway custom model deletion",
+      });
+    }
+    const removed = await deleteWorkspaceGatewayCustomModel(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      customModelId,
+      expectedVersion: parsed.data.expectedVersion,
+      operationId: parsed.data.operationId,
+      requestHash: workspaceCustomModelRequestHash({
+        action: "delete",
+        customModelId,
+        expectedVersion: parsed.data.expectedVersion,
+      }),
+    });
+    if (removed.outcome === "not_found") {
+      throw new HTTPException(404, {
+        message: "Gateway custom model not found",
+      });
+    }
+    if (removed.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "Gateway custom model changed; reload and retry",
+      });
+    }
+    return c.body(null, 204);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/openrouter-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const models = await listWorkspaceOpenRouterCustomModels(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      WorkspaceOpenRouterCustomModelsResponse.parse({
+        models: models.map(projectWorkspaceOpenRouterCustomModel),
+      }),
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/openrouter-custom-models", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
+    const parsed = CreateWorkspaceOpenRouterCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid OpenRouter custom model" });
+    }
+    const requestHash = workspaceCustomModelRequestHash({
+      action: "create",
+      upstreamModelId: parsed.data.upstreamModelId,
+      label: parsed.data.label ?? null,
+    });
+    const replay = await replayWorkspaceOpenRouterCustomModelCreate(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      operationId: parsed.data.operationId,
+      requestHash,
+    });
+    if (replay.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "OpenRouter custom model operation conflicts with current state",
+      });
+    }
+    if (replay.outcome === "success") {
+      return c.json(projectWorkspaceOpenRouterCustomModel(replay.model), 201);
+    }
+    const catalog = await deps.resolveCatalogSettings();
+    if (
+      configuredOpenRouterUpstreamModelIds(catalog.settings).includes(parsed.data.upstreamModelId)
+    ) {
+      throw new HTTPException(422, {
+        message: "OpenRouter model is already included in the deployment catalog",
+      });
+    }
+    const customProductId = `${WORKSPACE_OPENROUTER_MODEL_ID_PREFIX}${parsed.data.upstreamModelId}`;
+    const deploymentProductIds = new Set([
+      ...configuredModelInputIdentities(catalog.settings),
+      ...configuredOpenRouterWorkspaceProductModelIds(catalog.settings),
+    ]);
+    if (deploymentProductIds.has(customProductId)) {
+      throw new HTTPException(422, {
+        message: "OpenRouter model product id conflicts with the deployment catalog",
+      });
+    }
+    try {
+      const model = await createWorkspaceOpenRouterCustomModel(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        upstreamModelId: parsed.data.upstreamModelId,
+        label: parsed.data.label ?? null,
+        operationId: parsed.data.operationId,
+        requestHash,
+        createdBySubjectId: grant.subjectId,
+      });
+      if (!model || model.retiredAt) {
+        throw new HTTPException(409, {
+          message: "OpenRouter custom model operation conflicts with current state",
+        });
+      }
+      return c.json(projectWorkspaceOpenRouterCustomModel(model), 201);
+    } catch (error) {
+      if (
+        error instanceof WorkspaceOpenRouterCustomModelLimitError ||
+        error instanceof WorkspaceOpenRouterCustomModelHistoryLimitError
+      ) {
+        throw new HTTPException(422, { message: error.message });
+      }
+      if (nestedPostgresSqlState(error) === "23505") {
+        throw new HTTPException(422, {
+          message: "OpenRouter custom model already exists",
+        });
+      }
+      throw error;
+    }
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/openrouter-custom-models/:customModelId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
+    const customModelId = c.req.param("customModelId");
+    if (
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(
+        customModelId,
+      )
+    ) {
+      throw new HTTPException(422, {
+        message: "invalid OpenRouter custom model id",
+      });
+    }
+    const parsed = DeleteWorkspaceOpenRouterCustomModelRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(422, {
+        message: "invalid OpenRouter custom model deletion",
+      });
+    }
+    const removed = await deleteWorkspaceOpenRouterCustomModel(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      customModelId,
+      expectedVersion: parsed.data.expectedVersion,
+      operationId: parsed.data.operationId,
+      requestHash: workspaceCustomModelRequestHash({
+        action: "delete",
+        customModelId,
+        expectedVersion: parsed.data.expectedVersion,
+      }),
+    });
+    if (removed.outcome === "not_found") {
+      throw new HTTPException(404, {
+        message: "OpenRouter custom model not found",
+      });
+    }
+    if (removed.outcome === "conflict") {
+      throw new HTTPException(409, {
+        message: "OpenRouter custom model changed; reload and retry",
+      });
+    }
+    return c.body(null, 204);
+  });
+
   app.get("/v1/workspaces/:workspaceId/realtime-model-catalog", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
@@ -218,7 +943,7 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
         description: model.description,
         ...availability(
           Boolean(deps.settings.vercelAiGatewayApiKey),
-          "OpenGeni Gateway voice is not configured",
+          "Opengeni Gateway voice is not configured",
         ),
         recommended: index === 0,
       })),
@@ -262,35 +987,83 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 
   // Full replace (PUT, not merge): null/omitted = unrestricted for that
-  // dimension; an empty array is a valid explicit total block. Admin access —
-  // this decides whether turns can reach paid providers, so it is the same
-  // trust level as billing-affecting workspace settings.
+  // dimension; an empty array is a valid explicit total block. Settings access
+  // admits workspace administrators and the verified Personal owner, without
+  // widening membership or API-key delegation authority.
   app.put("/v1/workspaces/:workspaceId/model-policy", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-    const payload = UpdateWorkspaceModelPolicyRequest.parse(await c.req.json());
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
+    const payload = await parseRequestJson(c, UpdateWorkspaceModelPolicyRequest);
+    const catalog = await resolveWorkspaceCatalogSettings(deps.db, deps.settings, {
+      accountId: grant.accountId,
+      workspaceId,
+    });
     const policy = await upsertWorkspaceModelPolicy(deps.db, {
       accountId: grant.accountId,
       workspaceId,
       allowedProviders: payload.allowedProviders ?? null,
-      allowedModels: canonicalWorkspacePolicyModelIds(deps.settings, payload.allowedModels),
+      allowedModels: canonicalWorkspacePolicyModelIds(catalog.settings, payload.allowedModels),
     });
     return c.json(policy);
   });
 
-  app.post("/v1/workspaces/:workspaceId/inference-control", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/pause-timer", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
     if (workspaceControlUtf8Bytes(grant.subjectId) > WORKSPACE_CONTROL_ACTOR_MAX_BYTES) {
       throw new HTTPException(400, { message: "workspace-control actor is too large" });
     }
+    const parsed = WorkspacePauseTimerRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "Invalid pause timer" });
+    try {
+      await controlHumanWorkspaceTimer(
+        {
+          db: deps.db,
+          bus: deps.bus,
+          workflowClient: deps.workflowClient,
+          ...(deps.schedulePromptPostCommit
+            ? { schedulePromptPostCommit: deps.schedulePromptPostCommit }
+            : {}),
+        },
+        { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+        parsed.data,
+      );
+    } catch (error) {
+      if (error instanceof SessionControlConflictError)
+        throw new HTTPException(409, {
+          message: "Workspace changed. Reopen the timer and try again.",
+        });
+      if (error instanceof WorkspacePauseTimerInputError)
+        throw new HTTPException(400, { message: error.message });
+      throw error;
+    }
+    return c.json({ ok: true });
+  });
+
+  app.post("/v1/workspaces/:workspaceId/inference-control", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireWorkspaceSettingsGrant(c, deps, workspaceId);
+    if (workspaceControlUtf8Bytes(grant.subjectId) > WORKSPACE_CONTROL_ACTOR_MAX_BYTES) {
+      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(
-        { db: deps.db, bus: deps.bus, workflowClient: deps.workflowClient },
+        {
+          db: deps.db,
+          bus: deps.bus,
+          workflowClient: deps.workflowClient,
+          ...(deps.schedulePromptPostCommit
+            ? { schedulePromptPostCommit: deps.schedulePromptPostCommit }
+            : {}),
+        },
         { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
         parsed.data,
       ),
@@ -324,18 +1097,27 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       workspaceId,
       after,
       c.req.raw.signal,
-      { observability: deps.observability },
+      {
+        ...browserSseDeliveryOptions(c.req.query("transport")),
+        observability: deps.observability,
+        actorEpoch: getManagedAuthRequestActorEpoch(c.req.raw) ?? undefined,
+        reauthorize: async () => {
+          await requireFreshAccessGrant(c, deps, workspaceId, "workspace:read");
+        },
+      },
     );
   });
 
   app.put("/v1/workspaces/:workspaceId/default-rig", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "rigs:manage");
-    const payload = SetWorkspaceDefaultRigRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, SetWorkspaceDefaultRigRequest);
     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);
@@ -345,51 +1127,10 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.delete("/v1/workspaces/:workspaceId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-    // The DB transaction locks the account/workspace and every existing
-    // 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 deleted = await deleteWorkspaceIfQuiescent(deps.db, {
+    await deleteWorkspaceForRequest(deps, {
       accountId: grant.accountId,
       workspaceId,
     });
-    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" });
-    }
-    if (deleted.status === "active_sessions") {
-      throw new HTTPException(409, {
-        message: "stop the workspace's running sessions before deleting it",
-      });
-    }
-    if (deleted.status === "active_video_generations") {
-      throw new HTTPException(409, {
-        message: "wait for the workspace's active video generations to finish before deleting it",
-      });
-    }
-    if (deleted.status === "live_sandboxes") {
-      throw new HTTPException(409, {
-        message: "wait for the workspace's active sandboxes to finish draining before deleting it",
-      });
-    }
-    if (deleted.status !== "deleted") {
-      throw new Error(`Unhandled workspace deletion outcome: ${deleted.status}`);
-    }
-    // The cleanup claims were inserted in the same transaction as the cascade.
-    // Try them immediately; failures are released to the replica-safe outbox
-    // pump, so a process crash or Temporal outage cannot orphan the schedules.
-    await processTemporalScheduleCleanupClaims(
-      {
-        db: deps.db,
-        deleteSchedule: async (temporalScheduleId) => {
-          await deps.workflowClient.deleteScheduledTaskSchedule({ temporalScheduleId });
-        },
-        ...(deps.observability ? { observability: deps.observability } : {}),
-      },
-      deleted.temporalScheduleCleanups,
-    );
     return c.body(null, 204);
   });
 
@@ -398,28 +1139,75 @@ 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);
-    return c.json(ListWorkspaceMembersResponse.parse({ members }));
+    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);
+    const payload = await parseRequestJson(c, AddWorkspaceMemberRequest);
+    requireApiKeyDelegationContext(await requireAccessContext(c, deps), payload.permissions);
+    requireExplicitPermissionDelegation(grant, payload.permissions);
+    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" });
     }
@@ -430,21 +1218,35 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     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 payload = await parseRequestJson(c, UpdateWorkspaceMemberRequest);
+    requireApiKeyDelegationContext(await requireAccessContext(c, deps), payload.permissions);
+    requireExplicitPermissionDelegation(grant, payload.permissions);
+    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" });
@@ -458,12 +1260,85 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const subjectId = decodeURIComponent(c.req.param("subjectId"));
     const members = await listWorkspaceMembers(deps.db, workspaceId);
     // Never remove yourself, and never remove the last administering member.
-    assertWorkspaceMemberRemovable({ members, subjectId, callerSubjectId: grant.subjectId });
-    await removeWorkspaceMember(deps.db, workspaceId, subjectId);
+    // The fenced removal command re-enforces both guards fail-closed.
+    assertWorkspaceMemberRemovable({
+      members,
+      subjectId,
+      callerSubjectId: grant.subjectId,
+    });
+    await removeWorkspaceMember(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      actorSubjectId: grant.subjectId,
+      targetSubjectId: subjectId,
+    });
     return c.body(null, 204);
   });
 }
 
+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.
@@ -485,6 +1360,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}`,
+    });
   }
 }