@opengeni/api-router 0.11.2 → 0.11.8

package/dist/{chunk-BFWSDESE.js → chunk-DQWFAIPE.js}

@@ -7,8 +7,10 @@ import {
 } from "@opengeni/config";
 import {
   ClientConfig,
+  ErrorEnvelope,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   resolveWorkspaceMemoryEnabled
 } from "@opengeni/contracts";
 import {
@@ -24,7 +26,7 @@ import { bodyLimit } from "hono/body-limit";
 import { cors } from "hono/cors";
 import { HTTPException as HTTPException24 } from "hono/http-exception";
 import {
-  hasPermission as hasPermission5,
+  hasPermission as hasPermission7,
   requireAccessGrant as requireAccessGrant17,
   requirePermission,
   requireSessionAuthorization as requireSessionAuthorization3,
@@ -348,6 +350,7 @@ import {
 } from "@opengeni/db";
 import { appendAndPublishEvents as appendAndPublishEvents2, publishDurableSessionEvents } from "@opengeni/events";
 import {
+  createSignedState,
   createGitHubAppInstallationToken,
   GitHubAppConfigurationError,
   githubAppMissingSettings
@@ -355,46 +358,162 @@ import {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z4 from "zod/v4";
 import {
-  hasPermission,
+  hasPermission as hasPermission2,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope
 } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 
 // src/github-access.ts
-import { listGitHubInstallationAccessForWorkspace } from "@opengeni/db";
-import { listGitHubAppRepositories } from "@opengeni/github";
+import {
+  hasAuditableGitHubInstallationAuthority,
+  listGitHubInstallationAccessForWorkspace
+} from "@opengeni/db";
+import { listGitHubAppInstallationSummaries, listGitHubAppRepositories } from "@opengeni/github";
 async function listWorkspaceGitHubInstallationBindings(deps, workspaceId) {
   const installations = await listGitHubInstallationAccessForWorkspace(deps.db, workspaceId);
+  if (installations.length === 0) {
+    return [];
+  }
+  let liveById = /* @__PURE__ */ new Map();
+  let lifecycleVerified = false;
+  try {
+    if (deps.githubAppApi?.getInstallation) {
+      liveById = new Map(
+        await Promise.all(
+          installations.map(
+            async (installation) => [
+              installation.installationId,
+              await deps.githubAppApi.getInstallation({
+                installationId: installation.installationId
+              })
+            ]
+          )
+        )
+      );
+      lifecycleVerified = true;
+    } else if (!deps.githubAppApi) {
+      liveById = new Map(
+        (await listGitHubAppInstallationSummaries(deps.settings)).map((installation) => [
+          installation.installationId,
+          installation
+        ])
+      );
+      lifecycleVerified = true;
+    }
+  } catch {
+    liveById = /* @__PURE__ */ new Map();
+  }
   return installations.map((installation) => ({
     installationId: installation.installationId,
+    githubAccountId: installation.githubAccountId,
     accountLogin: installation.accountLogin,
     accountType: installation.accountType,
+    lifecycle: githubInstallationBindingLifecycle(
+      installation,
+      liveById,
+      installation.installationId,
+      lifecycleVerified
+    ),
     repositoryScope: installation.repositoryScope,
     repositoryCount: installation.repositoryIds.length,
     createdAt: installation.createdAt,
     updatedAt: installation.updatedAt
   }));
 }
+function githubBindingStatus(configured, installations) {
+  if (!configured) {
+    return "disabled";
+  }
+  return installations.some((installation) => installation.lifecycle === "active") ? "bound" : "unbound";
+}
+function githubInstallationBindingLifecycle(stored, liveById, installationId, lifecycleVerified) {
+  if (!hasAuditableGitHubInstallationAuthority(stored)) {
+    return "unverified";
+  }
+  if (!lifecycleVerified) {
+    return "unverified";
+  }
+  if (!liveById.has(installationId)) {
+    return "deleted";
+  }
+  const live = liveById.get(installationId);
+  if (!live) {
+    return "deleted";
+  }
+  if (live.suspended) {
+    return "suspended";
+  }
+  if (live.installationId !== installationId || stored.githubAccountId !== live.accountId) {
+    return "unverified";
+  }
+  return "active";
+}
 async function listWorkspaceGitHubRepositories(deps, workspaceId) {
+  const bindings = await listWorkspaceGitHubInstallationBindings(deps, workspaceId);
+  const activeInstallationIds = new Set(
+    bindings.filter((installation) => installation.lifecycle === "active").map((installation) => installation.installationId)
+  );
+  if (activeInstallationIds.size === 0) {
+    return [];
+  }
   const access = await listGitHubInstallationAccessForWorkspace(deps.db, workspaceId);
-  if (access.length === 0) {
+  const authorizedAccess = access.filter(
+    (installation) => activeInstallationIds.has(installation.installationId) && hasAuditableGitHubInstallationAuthority(installation)
+  );
+  if (authorizedAccess.length === 0) {
     return [];
   }
-  const installationIds = access.map((installation) => installation.installationId);
+  const installationIds = authorizedAccess.map((installation) => installation.installationId);
   const repositories = deps.githubAppApi?.listRepositories ? await deps.githubAppApi.listRepositories({ installationIds }) : await listGitHubAppRepositories(deps.settings, { installationIds });
   const accessByInstallation = new Map(
-    access.map((installation) => [installation.installationId, installation])
+    authorizedAccess.map((installation) => [installation.installationId, installation])
   );
   return repositories.filter((repository) => {
     const installation = accessByInstallation.get(repository.installationId);
     if (!installation) {
       return false;
     }
-    return installation.repositoryScope === "all" || installation.repositoryIds.includes(repository.id);
+    return installation.repositoryIds.includes(repository.id);
   });
 }
 
+// src/github-browser-flow.ts
+import { hasPermission } from "@opengeni/core";
+var githubBrowserGrantMaxAgeSeconds = 10 * 60;
+function githubBrowserGrantClaims(settings, grant, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  if (settings.productAccessMode !== "configured" || !hasPermission(grant.permissions, "github:manage")) {
+    return {};
+  }
+  return {
+    browserGrantSubjectId: grant.subjectId,
+    browserGrantExpiresAt: nowSeconds + githubBrowserGrantMaxAgeSeconds
+  };
+}
+function continuedGitHubBrowserGrantClaims(payload) {
+  return typeof payload.browserGrantSubjectId === "string" && typeof payload.browserGrantExpiresAt === "number" ? {
+    browserGrantSubjectId: payload.browserGrantSubjectId,
+    browserGrantExpiresAt: payload.browserGrantExpiresAt
+  } : {};
+}
+function githubBrowserGrantFromState(settings, payload, workspaceId, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  const subjectId = payload.browserGrantSubjectId;
+  const expiresAt = payload.browserGrantExpiresAt;
+  if (settings.productAccessMode !== "configured" || typeof payload.accountId !== "string" || payload.workspaceId !== workspaceId || typeof subjectId !== "string" || subjectId.length === 0 || typeof expiresAt !== "number" || !Number.isInteger(expiresAt) || expiresAt < nowSeconds || expiresAt > payload.iat + githubBrowserGrantMaxAgeSeconds) {
+    return null;
+  }
+  return {
+    accountId: payload.accountId,
+    workspaceId,
+    subjectId,
+    permissions: ["github:manage"],
+    metadata: { githubBrowserHandoff: true, expiresAt }
+  };
+}
+function githubBrowserBaseUrl(settings, requestOrigin) {
+  return (settings.githubAppManifestBaseUrl ?? settings.publicBaseUrl ?? requestOrigin ?? "").replace(/\/+$/, "");
+}
+
 // src/mcp/server.ts
 import {
   promoteVerifiedDefinitionEditChangeForApi,
@@ -1887,7 +2006,7 @@ function buildOpenGeniMcpServer(deps, grant, options = {}) {
   const json = (value) => ({
     content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
   });
-  const can = (permission) => hasPermission(grant.permissions, permission);
+  const can = (permission) => hasPermission2(grant.permissions, permission);
   const toolspaceMode = options.toolspace != null;
   const sessionId = typeof grant.metadata?.["sessionId"] === "string" ? grant.metadata["sessionId"] : null;
   if (sessionId !== null && (!toolspaceMode || can("sessions:control"))) {
@@ -1923,7 +2042,7 @@ function buildOpenGeniMcpServer(deps, grant, options = {}) {
   registerWorkspaceOrchestrationTools(server, deps, grant, can, sessionId, toolspaceMode, json);
   registerVariableSetTools(server, deps, grant, can, json);
   if (can("github:use")) {
-    registerGitHubConnectTool(server, deps, json);
+    registerGitHubConnectTool(server, deps, grant, options, json);
     if (sessionId !== null) {
       registerGitHubTokenTool(server, deps, grant, sessionId, json);
     }
@@ -3471,11 +3590,11 @@ function registerVariableSetTools(server, deps, grant, can, json) {
     );
   }
 }
-function registerGitHubConnectTool(server, deps, json) {
+function registerGitHubConnectTool(server, deps, grant, options, json) {
   server.registerTool(
     "github_connect_link",
     {
-      description: "Report GitHub App connection availability. New installation binding is disabled until GitHub installation authority can be proven, so installUrl and linkUrl are null.",
+      description: "Report truthful GitHub App workspace binding status and, for a human grant with github:manage, return the fresh GitHub owner-consent link. Server App configuration alone is never reported as a usable binding.",
       inputSchema: {}
     },
     async () => {
@@ -3485,17 +3604,30 @@ function registerGitHubConnectTool(server, deps, json) {
       if (missing.length > 0 || !slug) {
         return json({
           configured: false,
+          status: "disabled",
           appSlug: slug,
           installUrl: null,
           linkUrl: null,
           missing
         });
       }
+      const installations = await listWorkspaceGitHubInstallationBindings(deps, grant.workspaceId);
+      const status = githubBindingStatus(true, installations);
+      const baseUrl = githubBrowserBaseUrl(settings, options.requestOrigin);
+      const state = baseUrl && hasPermission2(grant.permissions, "github:manage") ? createSignedState(deps.githubStateSecret, {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        intent: "installation_authority",
+        ...githubBrowserGrantClaims(settings, grant)
+      }) : null;
+      const connectUrl = state ? `${baseUrl}/v1/workspaces/${grant.workspaceId}/github/connect?state=${encodeURIComponent(state)}` : null;
       return json({
         configured: true,
+        status,
         appSlug: slug,
-        installUrl: null,
-        linkUrl: null,
+        installUrl: connectUrl,
+        linkUrl: connectUrl,
+        installations,
         missing: []
       });
     }
@@ -3546,7 +3678,7 @@ function registerGitHubTokenTool(server, deps, grant, sessionId, json) {
   );
 }
 function requireVariableSetsUseForMcpAttachment(grant, variableSetId) {
-  if (variableSetId !== void 0 && !hasPermission(grant.permissions, "variable-sets:use")) {
+  if (variableSetId !== void 0 && !hasPermission2(grant.permissions, "variable-sets:use")) {
     throw new Error("missing permission: variable-sets:use");
   }
 }
@@ -3898,7 +4030,7 @@ import {
   prefixedMcpToolName
 } from "@opengeni/contracts";
 import {
-  hasPermission as hasPermission2,
+  hasPermission as hasPermission3,
   settingsWithEnabledCapabilityMcpServers
 } from "@opengeni/core";
 import {
@@ -4002,7 +4134,7 @@ function toolspaceAuthorityForGrant(grant) {
   return typeof sessionId === "string" ? { sessionId } : null;
 }
 function isToolspaceGrant(settings, grant) {
-  return settings.toolspaceEnabled && hasPermission2(grant.permissions, "toolspace:call") && toolspaceAuthorityForGrant(grant) !== null;
+  return settings.toolspaceEnabled && hasPermission3(grant.permissions, "toolspace:call") && toolspaceAuthorityForGrant(grant) !== null;
 }
 async function prepareToolspaceMcpSurface(input) {
   const { deps, grant } = input;
@@ -5103,8 +5235,8 @@ import {
   upsertCodexSubscriptionCredential,
   withCodexCapacityMutation
 } from "@opengeni/db";
-import { createSignedState, readSignedState } from "@opengeni/github";
-import { hasPermission as hasPermission3, requireAccessGrant as requireAccessGrant2 } from "@opengeni/core";
+import { createSignedState as createSignedState2, readSignedState } from "@opengeni/github";
+import { hasPermission as hasPermission4, requireAccessGrant as requireAccessGrant2 } from "@opengeni/core";
 import { HTTPException as HTTPException5 } from "hono/http-exception";
 import * as z from "zod/v4";
 
@@ -5490,7 +5622,7 @@ function registerCodexRoutes(app, deps) {
         message: error instanceof CodexDeviceError ? error.message : "failed to start Codex device login"
       });
     }
-    const state = createSignedState(githubStateSecret, {
+    const state = createSignedState2(githubStateSecret, {
       workspaceId,
       deviceAuthId: start.deviceAuthId,
       userCode: start.userCode
@@ -5877,7 +6009,7 @@ function registerCodexRoutes(app, deps) {
     const grant = await requireAccessGrant2(c, deps, workspaceId, "workspace:read");
     const human = await managedCookieHuman(c, deps);
     const accounts = await listCodexAccountStatuses(db, workspaceId);
-    const ownerRecoveries = human && human.subjectId === grant.subjectId && hasPermission3(grant.permissions, "workspace:admin") ? await listCodexResetRedemptionRecoveries(db, {
+    const ownerRecoveries = human && human.subjectId === grant.subjectId && hasPermission4(grant.permissions, "workspace:admin") ? await listCodexResetRedemptionRecoveries(db, {
       accountId: grant.accountId,
       workspaceId,
       subjectId: human.subjectId
@@ -5892,7 +6024,7 @@ function registerCodexRoutes(app, deps) {
         const account = queue.shift();
         if (!account) return;
         const canResumeRedemption = Boolean(
-          human && human.subjectId === grant.subjectId && human.subjectId === account.connectedBySubjectId && hasPermission3(grant.permissions, "workspace:admin")
+          human && human.subjectId === grant.subjectId && human.subjectId === account.connectedBySubjectId && hasPermission4(grant.permissions, "workspace:admin")
         );
         const canRedeem = canResumeRedemption && account.status === "active";
         overview[account.id] = await fetchCodexAccountOverview(
@@ -5928,7 +6060,7 @@ function registerCodexRoutes(app, deps) {
       await Promise.all(
         accounts.filter((account) => overview[account.id] == null).map(async (account) => {
           const canResumeRedemption = Boolean(
-            human && human.subjectId === grant.subjectId && human.subjectId === account.connectedBySubjectId && hasPermission3(grant.permissions, "workspace:admin")
+            human && human.subjectId === grant.subjectId && human.subjectId === account.connectedBySubjectId && hasPermission4(grant.permissions, "workspace:admin")
           );
           const fallback = await fetchCodexAccountOverview(
             deps,
@@ -6275,7 +6407,7 @@ import {
   storeIntegrationOAuthClient,
   updateConnection
 } from "@opengeni/db";
-import { createSignedState as createSignedState2, readSignedState as readSignedState2 } from "@opengeni/github";
+import { createSignedState as createSignedState3, readSignedState as readSignedState2 } from "@opengeni/github";
 import {
   DestinationPolicyError,
   OAUTH_MAX_RESPONSE_BYTES,
@@ -6347,7 +6479,7 @@ async function startMcpOAuth(deps, context) {
     context.payload.oauthClient
   );
   const key = requireEnvironmentEncryption(settings);
-  const state = createSignedState2(requireIntegrationsStateSecret(settings), {
+  const state = createSignedState3(requireIntegrationsStateSecret(settings), {
     accountId: context.accountId,
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
@@ -7543,6 +7675,7 @@ function encryptCredentialBundle(key, credential) {
 // src/routes/documents.ts
 import {
   AddDocumentRequest,
+  CreateKnowledgeDropRequest,
   CreateKnowledgeMemoryRequest,
   CreateDocumentBaseRequest,
   Document,
@@ -7550,11 +7683,14 @@ import {
   DocumentSearchRequest,
   KnowledgeMemory,
   KnowledgeMemorySearchRequest,
+  MoveDocumentRequest,
   UpdateKnowledgeMemoryRequest,
   WorkspaceMemorySearchRequest,
   WorkspaceMemorySearchResponse
 } from "@opengeni/contracts";
 import {
+  completeFileUpload as completeFileUpload2,
+  createFileUpload as createFileUpload2,
   createKnowledgeMemory as createKnowledgeMemory2,
   getKnowledgeMemory,
   listKnowledgeMemories as listKnowledgeMemories2,
@@ -7566,17 +7702,19 @@ import {
   addDocumentToBase,
   createDocumentBase,
   deleteDocumentFromBase,
+  ensureDefaultBase,
   getDocument,
   getDocumentBase,
   listDocumentBases as listDocumentBases2,
   listDocuments,
+  moveDocumentToBase,
   queueDocumentForReindex,
   searchDocuments as searchDocuments2
 } from "@opengeni/documents";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import { HTTPException as HTTPException9 } from "hono/http-exception";
-import { requireAccessGrant as requireAccessGrant4 } from "@opengeni/core";
-import { recordWorkspaceUsage as recordWorkspaceUsage2, requireLimit as requireLimit2 } from "@opengeni/core";
+import { HTTPException as HTTPException10 } from "hono/http-exception";
+import { requireAccessGrant as requireAccessGrant5 } from "@opengeni/core";
+import { recordWorkspaceUsage as recordWorkspaceUsage3, requireLimit as requireLimit3 } from "@opengeni/core";
 
 // src/mcp/documents.ts
 import {
@@ -7619,6 +7757,10 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
     name: "opengeni-documents",
     version: "1.0.0"
   });
+  const agentAccess = {
+    agentOnly: true,
+    ...options.viewerSubjectId ? { viewerSubjectId: options.viewerSubjectId } : {}
+  };
   server.registerTool(
     "list_document_bases",
     {
@@ -7635,7 +7777,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       description: "Search indexed documents with hybrid, vector, or keyword retrieval.",
       inputSchema: SearchInputSchema
     },
-    async (input) => searchContent(db, workspaceId, documentServices, input)
+    async (input) => searchContent(db, workspaceId, documentServices, input, agentAccess)
   );
   server.registerTool(
     "knowledge_search",
@@ -7643,7 +7785,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       description: "Search company knowledge sources with optional base, source-kind, ACL, and retrieval-mode filters.",
       inputSchema: SearchInputSchema
     },
-    async (input) => searchContent(db, workspaceId, documentServices, input)
+    async (input) => searchContent(db, workspaceId, documentServices, input, agentAccess)
   );
   server.registerTool(
     "fetch_document_chunk",
@@ -7654,7 +7796,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       }
     },
     async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, workspaceId, chunkId);
+      const found = await getDocumentChunk(db, workspaceId, chunkId, agentAccess);
       return {
         content: [
           { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` }
@@ -7672,7 +7814,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       }
     },
     async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, workspaceId, chunkId);
+      const found = await getDocumentChunk(db, workspaceId, chunkId, agentAccess);
       return {
         content: [
           { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` }
@@ -7749,7 +7891,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
   );
   return server;
 }
-async function searchContent(db, workspaceId, documentServices, input) {
+async function searchContent(db, workspaceId, documentServices, input, access) {
   return {
     content: [
       {
@@ -7764,7 +7906,8 @@ async function searchContent(db, workspaceId, documentServices, input) {
               ...input.limit ? { limit: input.limit } : {},
               ...input.mode ? { mode: input.mode } : {},
               ...input.sourceKinds ? { sourceKinds: input.sourceKinds } : {},
-              ...input.aclTags ? { aclTags: input.aclTags } : {}
+              ...input.aclTags ? { aclTags: input.aclTags } : {},
+              access
             },
             documentServices
           )
@@ -7774,1773 +7917,1933 @@ async function searchContent(db, workspaceId, documentServices, input) {
   };
 }
 
-// src/routes/documents.ts
-function registerDocumentRoutes(app, deps) {
-  const { db, objectStorage, documentIndexer, getDocumentServices } = deps;
-  app.post("/v1/workspaces/:workspaceId/document-bases", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:manage");
-    const payload = CreateDocumentBaseRequest.parse(await c.req.json());
-    return c.json(
-      DocumentBase.parse(
-        await createDocumentBase(db, { ...payload, accountId: grant.accountId, workspaceId })
-      ),
-      201
-    );
-  });
-  app.get("/v1/workspaces/:workspaceId/document-bases", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    return c.json(
-      (await listDocumentBases2(db, workspaceId)).map((base) => DocumentBase.parse(base))
-    );
-  });
-  app.get("/v1/workspaces/:workspaceId/document-bases/:baseId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const base = await getDocumentBase(db, workspaceId, c.req.param("baseId"));
-    if (!base) {
-      throw new HTTPException9(404, { message: "document base not found" });
-    }
-    return c.json(DocumentBase.parse(base));
-  });
-  app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
+// src/routes/files.ts
+import {
+  CompleteFileUploadResponse,
+  CreateFileUploadRequest,
+  CreateFileUploadResponse,
+  FileAsset,
+  FileDownloadUrlResponse,
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+  RetainedArtifactMetadataSchema,
+  retainedArtifactReferenceFromFile,
+  resolveRetainedOutputRange
+} from "@opengeni/contracts";
+import {
+  claimFileUploadCleanup,
+  completeFileUploadCleanup,
+  completeFileUpload,
+  createFileUpload,
+  getFileUpload,
+  getRetainedFileArtifact,
+  requireFile as requireFile2
+} from "@opengeni/db";
+import { HTTPException as HTTPException9 } from "hono/http-exception";
+import { requireAccessGrant as requireAccessGrant4 } from "@opengeni/core";
+import { recordWorkspaceUsage as recordWorkspaceUsage2, requireLimit as requireLimit2 } from "@opengeni/core";
+function registerFileRoutes(app, deps) {
+  const { db, objectStorage } = deps;
+  app.post("/v1/workspaces/:workspaceId/files/uploads", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:manage");
+    const grant = await requireAccessGrant4(c, deps, workspaceId, "files:upload");
     if (!objectStorage) {
       throw new HTTPException9(503, { message: "object storage is not configured" });
     }
+    const payload = CreateFileUploadRequest.parse(await c.req.json());
     await requireLimit2(deps, {
       accountId: grant.accountId,
       workspaceId,
-      action: "document:index",
-      quantity: 0
+      action: "file:upload",
+      quantity: payload.sizeBytes
     });
-    const payload = AddDocumentRequest.parse(await c.req.json());
-    try {
-      const document = await addDocumentToBase(db, {
-        ...payload,
-        accountId: grant.accountId,
-        workspaceId,
-        baseId: c.req.param("baseId")
+    if (payload.sizeBytes > objectStorage.maxSinglePutSizeBytes) {
+      throw new HTTPException9(413, {
+        message: `file exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes`
       });
-      const wasCreated = document.status === "queued" && document.chunkCount === 0 && document.error === null;
-      const indexed = document.status === "ready" ? document : await documentIndexer.indexDocument({
-        accountId: grant.accountId,
-        workspaceId,
-        documentId: document.id
-      }) ?? document;
-      if (indexed.status === "ready") {
-        await recordWorkspaceUsage2(deps, {
-          accountId: grant.accountId,
-          workspaceId,
-          subjectId: grant.subjectId,
-          eventType: "document.indexed",
-          quantity: indexed.chunkCount,
-          unit: "chunk",
-          sourceResourceType: "document",
-          sourceResourceId: indexed.id,
-          idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`
-        });
-      }
-      return c.json(Document.parse(indexed), wasCreated ? 201 : 200);
-    } catch (error) {
-      throw documentHttpException(error);
     }
-  });
-  app.get("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
+    const fileId = crypto.randomUUID();
+    const safeFilename = sanitizeFilename(payload.filename);
+    const objectKey = `workspaces/${workspaceId}/files/${fileId}/original/${safeFilename}`;
+    const signed = await objectStorage.createPutUrl({
+      key: objectKey,
+      contentType: payload.contentType,
+      ...payload.sha256 ? { sha256: payload.sha256 } : {}
+    });
+    const upload = await createFileUpload(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      fileId,
+      filename: payload.filename,
+      safeFilename,
+      contentType: payload.contentType,
+      sizeBytes: payload.sizeBytes,
+      sha256: payload.sha256 ?? null,
+      bucket: objectStorage.bucket,
+      objectKey,
+      expiresAt: signed.expiresAt
+    });
     return c.json(
-      (await listDocuments(db, workspaceId, c.req.param("baseId"))).map(
-        (document) => Document.parse(document)
-      )
+      CreateFileUploadResponse.parse({
+        fileId: upload.file.id,
+        uploadId: upload.uploadId,
+        putUrl: signed.url,
+        requiredHeaders: signed.requiredHeaders,
+        expiresAt: upload.expiresAt,
+        maxSizeBytes: objectStorage.maxSinglePutSizeBytes
+      }),
+      201
     );
   });
-  app.delete(
-    "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId",
-    async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:manage");
-      try {
-        await deleteDocumentFromBase(db, {
-          accountId: grant.accountId,
-          workspaceId,
-          baseId: c.req.param("baseId"),
-          documentId: c.req.param("documentId")
-        });
-        return c.body(null, 204);
-      } catch (error) {
-        throw documentHttpException(error);
-      }
+  app.post("/v1/workspaces/:workspaceId/files/uploads/:uploadId/complete", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant4(c, deps, workspaceId, "files:upload");
+    if (!objectStorage) {
+      throw new HTTPException9(503, { message: "object storage is not configured" });
     }
-  );
-  app.post(
-    "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId/reindex",
-    async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:manage");
-      if (!objectStorage) {
-        throw new HTTPException9(503, { message: "object storage is not configured" });
-      }
-      await requireLimit2(deps, {
+    const upload = await getFileUpload(db, workspaceId, c.req.param("uploadId"));
+    if (!upload) {
+      throw new HTTPException9(404, { message: "file upload not found" });
+    }
+    const recordUploadedFileUsage = async (file2) => {
+      await recordWorkspaceUsage2(deps, {
         accountId: grant.accountId,
         workspaceId,
-        action: "document:index",
-        quantity: 0
+        subjectId: grant.subjectId,
+        eventType: "file.uploaded",
+        quantity: file2.sizeBytes,
+        unit: "byte",
+        sourceResourceType: "file",
+        sourceResourceId: file2.id,
+        idempotencyKey: `file.uploaded:${workspaceId}:${file2.id}`
       });
+    };
+    const completeAndRecordUsage = async () => {
+      let file2;
       try {
-        const document = await getDocument(db, workspaceId, c.req.param("documentId"));
-        if (!document) {
-          throw new HTTPException9(404, { message: "document not found" });
-        }
-        if (document.status !== "failed") {
-          throw new HTTPException9(422, { message: "only failed documents can be retried" });
-        }
-        if (document.baseId !== c.req.param("baseId")) {
-          throw new HTTPException9(404, { message: "document not found" });
-        }
-        const queued = await queueDocumentForReindex(db, workspaceId, document.id);
-        const indexed = await documentIndexer.indexDocument({
-          accountId: grant.accountId,
-          workspaceId,
-          documentId: document.id
-        }) ?? queued;
-        if (indexed.status === "ready") {
-          await recordWorkspaceUsage2(deps, {
-            accountId: grant.accountId,
-            workspaceId,
-            subjectId: grant.subjectId,
-            eventType: "document.indexed",
-            quantity: indexed.chunkCount,
-            unit: "chunk",
-            sourceResourceType: "document",
-            sourceResourceId: indexed.id,
-            idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`
-          });
-        }
-        return c.json(Document.parse(indexed));
+        file2 = await completeFileUpload(db, workspaceId, upload.id);
       } catch (error) {
-        if (error instanceof HTTPException9) {
+        const current = await getFileUpload(db, workspaceId, upload.id);
+        if (current?.status === "completed" && current.file.status === "ready") {
+          file2 = current.file;
+        } else if (current && current.status !== "pending") {
+          throw new HTTPException9(409, {
+            message: `file upload is ${publicFileUploadStatus(current.status)}`
+          });
+        } else {
           throw error;
         }
-        throw documentHttpException(error);
       }
+      await recordUploadedFileUsage(file2);
+      return file2;
+    };
+    const rejectAndCleanObject = async (status, message, terminalStatus) => {
+      const claim = await claimFileUploadCleanup(db, {
+        workspaceId,
+        uploadId: upload.id,
+        fileId: upload.file.id
+      });
+      if (claim.outcome === "completed") {
+        await recordUploadedFileUsage(claim.file);
+        return claim.file;
+      }
+      if (claim.outcome === "unavailable") {
+        throw new HTTPException9(409, {
+          message: `file upload is ${publicFileUploadStatus(claim.status)}`
+        });
+      }
+      try {
+        await objectStorage.deleteObject(upload.file.objectKey);
+      } catch (error) {
+        deps.observability?.warn(
+          "file upload rejection cleanup failed; claim remains reclaimable",
+          {
+            workspaceId,
+            fileId: upload.file.id,
+            uploadId: upload.id,
+            error: error instanceof Error ? error.message : String(error)
+          }
+        );
+        throw new HTTPException9(status, { message });
+      }
+      const settled = await completeFileUploadCleanup(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        uploadId: upload.id,
+        fileId: upload.file.id,
+        terminalStatus
+      });
+      if (!settled) {
+        throw new HTTPException9(409, { message: "file upload cleanup claim was superseded" });
+      }
+      throw new HTTPException9(status, { message });
+    };
+    if (upload.status === "completed" && upload.file.status === "ready") {
+      const file2 = await completeAndRecordUsage();
+      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
     }
-  );
-  app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/search", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const payload = DocumentSearchRequest.parse(await c.req.json());
-    const base = await getDocumentBase(db, workspaceId, c.req.param("baseId"));
-    if (!base) {
-      throw new HTTPException9(404, { message: "document base not found" });
-    }
-    return c.json({
-      results: await searchDocuments2(
-        db,
-        {
-          workspaceId,
-          baseIds: [base.id],
-          query: payload.query,
-          limit: payload.limit,
-          mode: payload.mode,
-          sourceKinds: payload.sourceKinds,
-          aclTags: payload.aclTags
-        },
-        getDocumentServices()
-      )
-    });
-  });
-  app.post("/v1/workspaces/:workspaceId/knowledge/search", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const payload = DocumentSearchRequest.parse(await c.req.json());
-    return c.json({
-      results: await searchDocuments2(
-        db,
-        {
-          workspaceId,
-          query: payload.query,
-          baseIds: payload.baseIds,
-          limit: payload.limit,
-          mode: payload.mode,
-          sourceKinds: payload.sourceKinds,
-          aclTags: payload.aclTags
-        },
-        getDocumentServices()
-      )
-    });
-  });
-  app.get("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const parsed = KnowledgeMemorySearchRequest.safeParse({
-      query: c.req.query("query") || void 0,
-      status: c.req.query("status") || void 0,
-      kind: c.req.query("kind") || void 0,
-      scope: c.req.query("scope") || void 0,
-      limit: c.req.query("limit") ? Number(c.req.query("limit")) : void 0
+    if (upload.status !== "pending") {
+      throw new HTTPException9(409, {
+        message: `file upload is ${publicFileUploadStatus(upload.status)}`
+      });
+    }
+    if (upload.expiresAt.getTime() < Date.now()) {
+      const file2 = await rejectAndCleanObject(409, "file upload has expired", "expired");
+      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
+    }
+    const head = await objectStorage.headFile(upload.file).catch((error) => {
+      throw new HTTPException9(409, {
+        message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}`
+      });
     });
-    if (!parsed.success) {
-      throw new HTTPException9(400, { message: "invalid knowledge memory query parameters" });
+    if (Number(head.ContentLength ?? -1) !== upload.file.sizeBytes) {
+      const file2 = await rejectAndCleanObject(
+        422,
+        "uploaded object size does not match file metadata",
+        "failed"
+      );
+      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
     }
-    return c.json(
-      (await listKnowledgeMemories2(db, workspaceId, parsed.data)).map(
-        (memory) => KnowledgeMemory.parse(memory)
-      )
-    );
+    if (upload.file.contentType && head.ContentType && head.ContentType !== upload.file.contentType) {
+      const file2 = await rejectAndCleanObject(
+        422,
+        "uploaded object content type does not match file metadata",
+        "failed"
+      );
+      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
+    }
+    if (upload.file.sha256 && head.Metadata?.sha256 !== upload.file.sha256) {
+      const file2 = await rejectAndCleanObject(
+        422,
+        "uploaded object checksum metadata does not match file metadata",
+        "failed"
+      );
+      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
+    }
+    const file = await completeAndRecordUsage();
+    return c.json(CompleteFileUploadResponse.parse({ file }));
   });
-  app.get("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const memory = await getKnowledgeMemory(db, workspaceId, c.req.param("memoryId"));
-    if (!memory) {
-      throw new HTTPException9(404, { message: "knowledge memory not found" });
+    await requireAccessGrant4(c, deps, workspaceId, "files:read");
+    const file = await requireFile2(db, workspaceId, c.req.param("fileId")).catch(() => null);
+    if (!file) {
+      throw new HTTPException9(404, { message: "file not found" });
     }
-    return c.json(KnowledgeMemory.parse(memory));
+    return c.json(FileAsset.parse(file));
   });
-  app.post("/v1/workspaces/:workspaceId/knowledge/memories/search", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const parsed = WorkspaceMemorySearchRequest.safeParse(await c.req.json());
-    if (!parsed.success) {
-      throw new HTTPException9(400, { message: "invalid workspace memory search request" });
+    await requireAccessGrant4(c, deps, workspaceId, "files:read");
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    if (!artifact) {
+      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
     }
-    const results = await searchWorkspaceMemories2(
-      db,
-      workspaceId,
-      parsed.data,
-      getDocumentServices().embedder
-    );
-    return c.json(
-      WorkspaceMemorySearchResponse.parse({
-        results: results.map((result) => ({
-          ...result,
-          memory: KnowledgeMemory.parse(result.memory)
-        }))
-      })
-    );
+    return c.json(retainedArtifactMetadata(artifact));
   });
-  app.post("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId/content", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:manage");
-    const parsedBody = CreateKnowledgeMemoryRequest.safeParse(await c.req.json());
-    if (!parsedBody.success) {
-      throw new HTTPException9(400, { message: "invalid knowledge memory request" });
+    await requireAccessGrant4(c, deps, workspaceId, "files:read");
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    if (!artifact) {
+      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
     }
-    const payload = parsedBody.data;
-    if (payload.status === "active") {
-      try {
-        const result = await saveWorkspaceMemory2(
-          db,
-          {
-            accountId: grant.accountId,
-            workspaceId,
-            text: payload.text,
-            kind: payload.kind,
-            confidence: payload.confidence,
-            pinned: payload.pinned,
-            replacesId: payload.replacesId ?? null,
-            metadata: payload.metadata,
-            origin: "human"
-          },
-          getDocumentServices().embedder
-        );
-        return c.json(KnowledgeMemory.parse(result.memory), 201);
-      } catch (error) {
-        throw documentHttpException(error);
-      }
+    const metadata = retainedArtifactMetadata(artifact);
+    if (!metadata.available) {
+      return c.json(metadata, retainedArtifactUnavailableStatus(metadata.reason));
     }
-    return c.json(
-      KnowledgeMemory.parse(
-        await createKnowledgeMemory2(db, {
-          ...payload,
-          accountId: grant.accountId,
-          workspaceId
-        })
-      ),
-      201
+    if (!objectStorage) {
+      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 503);
+    }
+    const rangeHeader = c.req.header("range");
+    const range = resolveRetainedOutputRange(
+      rangeHeader,
+      metadata.originalBytes,
+      rangeHeader ? RETAINED_OUTPUT_MAX_PAGE_BYTES : RETAINED_OUTPUT_DEFAULT_PAGE_BYTES
     );
-  });
-  app.patch("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:manage");
-    const payload = UpdateKnowledgeMemoryRequest.parse(await c.req.json());
-    const reviewedBy = payload.reviewedBy ?? (payload.status === "approved" || payload.status === "rejected" ? grant.subjectLabel ?? grant.subjectId : void 0);
-    try {
+    if (range.kind === "invalid") {
       return c.json(
-        KnowledgeMemory.parse(
-          await updateKnowledgeMemory(
-            db,
-            workspaceId,
-            c.req.param("memoryId"),
-            {
-              ...payload,
-              ...reviewedBy ? { reviewedBy } : {}
-            },
-            getDocumentServices().embedder
-          )
-        )
+        {
+          message: "invalid retained artifact byte range",
+          reason: range.reason,
+          maxRangeBytes: RETAINED_OUTPUT_MAX_PAGE_BYTES
+        },
+        400
       );
-    } catch (error) {
-      throw documentHttpException(error);
     }
-  });
-  app.all("/v1/workspaces/:workspaceId/mcp/docs", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant4(c, deps, workspaceId, "documents:search");
-    const sessionId = typeof grant.metadata?.sessionId === "string" ? grant.metadata.sessionId : void 0;
-    const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
-    const server = buildDocumentsMcpServer(
-      db,
-      grant.accountId,
-      workspaceId,
-      getDocumentServices(),
-      { createdBySessionId: sessionId }
-    );
-    await server.connect(transport);
-    return await transport.handleRequest(c.req.raw);
-  });
-}
-function documentHttpException(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (message.includes("not found")) {
-    return new HTTPException9(404, { message });
-  }
-  if (message.includes("pending") || message.includes("failed") || message.includes("deleted")) {
-    return new HTTPException9(422, { message });
-  }
-  if (message.includes("too long") || message.includes("visible memory is full") || message.includes("empty after sanitization") || message.includes("does not match") || message.includes("Ambiguous memory id")) {
-    return new HTTPException9(400, { message });
-  }
-  return new HTTPException9(500, { message });
+    if (range.kind === "unsatisfiable") {
+      return c.json(
+        { message: "retained artifact byte range is not satisfiable", reason: range.reason },
+        416,
+        {
+          "Accept-Ranges": "bytes",
+          "Content-Range": range.contentRange,
+          "Cache-Control": "private, no-store"
+        }
+      );
+    }
+    const headers = {
+      "Accept-Ranges": range.acceptRanges,
+      "Cache-Control": "private, no-store",
+      "Content-Length": String(range.length),
+      "Content-Type": metadata.contentType,
+      "X-Content-Type-Options": "nosniff",
+      ...range.contentRange ? { "Content-Range": range.contentRange } : {}
+    };
+    if (range.kind === "empty") {
+      if (!await objectStorage.fileExists(artifact.file)) {
+        return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+      }
+      return c.body(null, 200, headers);
+    }
+    const bytes = await objectStorage.getFileRange(artifact.file, {
+      start: range.start,
+      end: range.end
+    });
+    if (!bytes) {
+      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+    }
+    if (bytes.byteLength !== range.length) {
+      throw new HTTPException9(502, { message: "object storage returned an invalid byte range" });
+    }
+    return c.body(new Uint8Array(bytes), range.status, headers);
+  });
+  app.post("/v1/workspaces/:workspaceId/files/:fileId/download-url", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant4(c, deps, workspaceId, "files:read");
+    if (!objectStorage) {
+      throw new HTTPException9(503, { message: "object storage is not configured" });
+    }
+    const file = await requireFile2(db, workspaceId, c.req.param("fileId")).catch(() => null);
+    if (!file) {
+      throw new HTTPException9(404, { message: "file not found" });
+    }
+    if (file.status !== "ready") {
+      throw new HTTPException9(409, { message: `file is ${file.status}` });
+    }
+    const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    return c.json(
+      FileDownloadUrlResponse.parse({
+        url: signed.url,
+        expiresAt: signed.expiresAt.toISOString()
+      })
+    );
+  });
 }
-
-// src/routes/enrollments.ts
-import {
-  DeviceEnrollmentApproveRequest,
-  DeviceEnrollmentApproveResponse,
-  DeviceEnrollmentDenyRequest,
-  DeviceEnrollmentDenyResponse,
-  DeviceEnrollmentLookupRequest,
-  DeviceEnrollmentLookupResponse,
-  DeviceEnrollmentPollRequest,
-  DeviceEnrollmentStartRequest,
-  EnrollmentSummary,
-  EnrollTokenExchangeRequest,
-  EnrollTokenExchangeResponse,
-  ListEnrollmentsResponse,
-  MintEnrollTokenRequest,
-  MintEnrollTokenResponse,
-  RevokeEnrollmentResponse
-} from "@opengeni/contracts";
-import { getWorkspace, listEnrollments, revokeEnrollment } from "@opengeni/db";
-import { HTTPException as HTTPException10 } from "hono/http-exception";
-import { requireAccessGrant as requireAccessGrant5 } from "@opengeni/core";
-
-// src/sandbox/enrollment.ts
-import { randomBytes as randomBytes2 } from "crypto";
-import {
-  resolveEnrollmentSigningSecret,
-  resolveRelayTokenSecret
-} from "@opengeni/config";
-import {
-  DeviceEnrollmentState,
-  signEnrollmentBearer,
-  signEnrollToken,
-  signRelayToken,
-  verifyEnrollToken
-} from "@opengeni/contracts";
-import {
-  approveDeviceEnrollmentRequest,
-  consumeDeviceEnrollmentRequest,
-  createDeviceEnrollmentRequest,
-  denyDeviceEnrollmentRequest,
-  finalizeEnrollmentByToken,
-  getDeviceEnrollmentRequestByDeviceCode,
-  getEnrollment,
-  getPendingDeviceEnrollmentRequestByUserCode,
-  getPendingDeviceEnrollmentRequestByUserCodeGlobal
-} from "@opengeni/db";
-import { relayDialBaseFromSettings } from "@opengeni/core";
-var DEVICE_CODE_TTL_SECONDS = 600;
-var DEVICE_POLL_INTERVAL_SECONDS = 5;
-var ENROLLMENT_BEARER_TTL_SECONDS = 30 * 24 * 3600;
-var RELAY_TOKEN_TTL_SECONDS = 30 * 24 * 3600;
-var ENROLL_TOKEN_TTL_SECONDS = 3600;
-function mintDeviceCode() {
-  return randomBytes2(32).toString("base64url");
+function sanitizeFilename(filename) {
+  const trimmed = filename.trim().replace(/[/\\]/g, "_");
+  const safe = trimmed.replace(/[^A-Za-z0-9._ -]+/g, "_").replace(/\s+/g, " ").trim();
+  return safe || "file";
 }
-var USER_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
-function mintUserCode() {
-  const bytes = randomBytes2(8);
-  let out = "";
-  for (let i = 0; i < 8; i += 1) {
-    out += USER_CODE_ALPHABET[bytes[i] % USER_CODE_ALPHABET.length];
+function publicFileUploadStatus(status) {
+  return status === "cleanup_pending" ? "failed" : status;
+}
+function retainedArtifactId(value) {
+  const parsed = FileAsset.shape.id.safeParse(value);
+  if (!parsed.success) {
+    throw new HTTPException9(404, { message: "artifact not found" });
   }
-  return `${out.slice(0, 4)}-${out.slice(4, 8)}`;
+  return parsed.data;
 }
-async function startDeviceEnrollment(services, input) {
-  const { db } = services;
-  const expiresAt = new Date(Date.now() + DEVICE_CODE_TTL_SECONDS * 1e3);
-  let request;
-  let lastError;
-  for (let attempt = 0; attempt < 5 && !request; attempt += 1) {
-    const deviceCode = mintDeviceCode();
-    const userCode = mintUserCode();
-    try {
-      request = await createDeviceEnrollmentRequest(db, {
-        accountId: input.accountId,
-        workspaceId: input.workspaceId,
-        deviceCode,
-        userCode,
-        pubkey: input.publicKey,
-        os: input.os,
-        arch: input.arch,
-        machineName: input.machineName ?? null,
-        requestedExposure: "whole-machine",
-        canOfferDisplay: input.canOfferDisplay,
-        requestsScreenControl: input.requestsScreenControl,
-        expiresAt
-      });
-    } catch (error) {
-      lastError = error;
-    }
+function retainedArtifactUnavailable(artifactId, reason) {
+  return RetainedArtifactMetadataSchema.parse({ available: false, artifactId, reason });
+}
+function retainedArtifactMetadata(artifact) {
+  const reference = retainedArtifactReferenceFromFile(artifact.file);
+  if (reference) return reference;
+  const { file, uploadStatus, uploadExpiresAt } = artifact;
+  if (file.status === "deleted") {
+    return retainedArtifactUnavailable(file.id, "deleted");
   }
-  if (!request) {
-    throw lastError instanceof Error ? lastError : new Error("failed to start device enrollment");
+  if (file.status === "expired" || uploadStatus === "expired" || uploadStatus === "pending" && uploadExpiresAt !== null && uploadExpiresAt.getTime() < Date.now()) {
+    return retainedArtifactUnavailable(file.id, "expired");
   }
-  const base = input.verificationOrigin.replace(/\/$/, "");
-  const verificationUri = `${base}/device`;
-  const verificationUriComplete = `${verificationUri}?user_code=${encodeURIComponent(request.userCode)}`;
-  return {
-    deviceCode: request.deviceCode,
-    userCode: request.userCode,
-    verificationUri,
-    verificationUriComplete,
-    intervalSeconds: DEVICE_POLL_INTERVAL_SECONDS,
-    expiresInSeconds: DEVICE_CODE_TTL_SECONDS
-  };
-}
-async function approveDeviceEnrollment(services, input) {
-  const { db } = services;
-  const pending = await getPendingDeviceEnrollmentRequestByUserCode(
-    db,
-    input.workspaceId,
-    input.userCode
-  );
-  if (!pending) {
-    return null;
+  if (file.status === "failed" || uploadStatus === "failed" || uploadStatus === "cleanup_pending") {
+    return retainedArtifactUnavailable(file.id, "failed");
   }
-  const sandboxName = (pending.machineName?.trim() || `${pending.os} machine`).slice(0, 256);
-  const result = await approveDeviceEnrollmentRequest(db, {
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    requestId: pending.id,
-    allowScreenControl: input.allowScreenControl,
-    approvedBySubjectId: input.approvedBySubjectId,
-    approvedBySubjectLabel: input.approvedBySubjectLabel ?? null,
-    sandboxName
-  });
-  if (!result.approved || !result.enrollment || !result.sandbox) {
-    return null;
+  if (file.status === "pending_upload" || uploadStatus === "pending") {
+    return retainedArtifactUnavailable(file.id, "pending");
   }
-  return {
-    enrollmentId: result.enrollment.id,
-    sandboxId: result.sandbox.id,
-    allowScreenControl: result.enrollment.allowScreenControl
-  };
-}
-async function lookupDeviceEnrollment(services, input) {
-  const { db } = services;
-  return await getPendingDeviceEnrollmentRequestByUserCodeGlobal(db, input.userCode);
-}
-function toLookupResponse(record3) {
-  return {
-    workspaceId: record3.workspaceId,
-    userCode: record3.userCode,
-    machine: {
-      machineName: record3.machineName,
-      os: record3.os,
-      arch: record3.arch,
-      canOfferDisplay: record3.canOfferDisplay,
-      requestsScreenControl: record3.requestsScreenControl
-    },
-    expiresAt: record3.expiresAt
-  };
+  return retainedArtifactUnavailable(file.id, "unsupported");
 }
-async function denyDeviceEnrollment(services, input) {
-  const { db } = services;
-  const pending = await getPendingDeviceEnrollmentRequestByUserCode(
-    db,
-    input.workspaceId,
-    input.userCode
-  );
-  if (!pending) {
-    return { denied: false };
+function retainedArtifactUnavailableStatus(reason) {
+  switch (reason) {
+    case "deleted":
+      return 404;
+    case "expired":
+    case "missing_storage":
+      return 410;
+    case "unsupported":
+    case "not_retained":
+    case "storage_write_failed":
+      return 422;
+    case "pending":
+    case "failed":
+      return 409;
   }
-  return await denyDeviceEnrollmentRequest(db, {
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    requestId: pending.id
-  });
-}
-async function mintEnrollToken(services, input) {
-  const { settings } = services;
-  const secret = resolveEnrollmentSigningSecret(settings);
-  if (!secret) {
-    return null;
-  }
-  const nowSeconds = Math.floor(Date.now() / 1e3);
-  const exp = nowSeconds + ENROLL_TOKEN_TTL_SECONDS;
-  const token = await signEnrollToken(secret, {
-    typ: "enroll",
-    workspaceId: input.workspaceId,
-    accountId: input.accountId,
-    allowScreenControl: input.allowScreenControl,
-    iat: nowSeconds,
-    exp
-  });
-  return {
-    token,
-    expiresAt: new Date(exp * 1e3).toISOString(),
-    expiresInSeconds: ENROLL_TOKEN_TTL_SECONDS
-  };
 }
-async function exchangeEnrollToken(services, input) {
-  const { db, settings } = services;
-  const secret = resolveEnrollmentSigningSecret(settings);
-  if (!secret) {
-    return { ok: false, reason: "disabled" };
-  }
-  const claims = await verifyEnrollToken(secret, input.token);
-  if (!claims) {
-    return { ok: false, reason: "invalid" };
-  }
-  const sandboxName = (input.machineName?.trim() || `${input.os} machine`).slice(0, 256);
-  const { enrollment } = await finalizeEnrollmentByToken(db, {
-    accountId: claims.accountId,
-    workspaceId: claims.workspaceId,
-    pubkey: input.publicKey,
-    hasDisplay: input.canOfferDisplay,
-    // The token's allowScreenControl is the AUTHORITATIVE consent (NOT the agent's
-    // requestsScreenControl) — it was baked in at mint by the authorizing user.
-    allowScreenControl: claims.allowScreenControl,
-    os: input.os,
-    arch: input.arch,
-    sandboxName
+
+// src/routes/documents.ts
+function registerDocumentRoutes(app, deps) {
+  const { db, objectStorage, documentIndexer, getDocumentServices } = deps;
+  app.post("/v1/workspaces/:workspaceId/document-bases", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    const payload = CreateDocumentBaseRequest.parse(await c.req.json());
+    return c.json(
+      DocumentBase.parse(
+        await createDocumentBase(db, { ...payload, accountId: grant.accountId, workspaceId })
+      ),
+      201
+    );
   });
-  const credentials = await buildEnrollmentCredentials(services, {
-    secret,
-    workspaceId: claims.workspaceId,
-    agentId: enrollment.id,
-    consentedScreenControl: enrollment.allowScreenControl
+  app.get("/v1/workspaces/:workspaceId/document-bases", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    return c.json(
+      (await listDocumentBases2(db, workspaceId)).map((base) => DocumentBase.parse(base))
+    );
   });
-  return { ok: true, credentials };
-}
-async function pollDeviceEnrollment(services, input) {
-  const { db, settings } = services;
-  const request = await getDeviceEnrollmentRequestByDeviceCode(db, input.deviceCode);
-  if (!request) {
-    return { state: "expired" };
-  }
-  if (request.status === "denied") {
-    return { state: "denied" };
-  }
-  if (request.status === "pending") {
-    if (new Date(request.expiresAt).getTime() <= Date.now()) {
-      return { state: "expired" };
+  app.get("/v1/workspaces/:workspaceId/document-bases/:baseId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const base = await getDocumentBase(db, workspaceId, c.req.param("baseId"));
+    if (!base) {
+      throw new HTTPException10(404, { message: "document base not found" });
     }
-    return { state: "pending" };
-  }
-  if (!request.enrollmentId) {
-    return { state: "expired" };
-  }
-  const secret = resolveEnrollmentSigningSecret(settings);
-  if (!secret) {
-    return { state: "disabled" };
-  }
-  const enrollment = await getEnrollment(db, request.workspaceId, request.enrollmentId);
-  if (!enrollment || enrollment.status !== "active") {
-    return { state: "denied" };
-  }
-  const credentials = await buildEnrollmentCredentials(services, {
-    secret,
-    workspaceId: request.workspaceId,
-    agentId: enrollment.id,
-    consentedScreenControl: enrollment.allowScreenControl
+    return c.json(DocumentBase.parse(base));
   });
-  if (request.status === "approved") {
-    await consumeDeviceEnrollmentRequest(db, {
-      accountId: request.accountId,
-      workspaceId: request.workspaceId,
-      requestId: request.id
+  app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    if (!objectStorage) {
+      throw new HTTPException10(503, { message: "object storage is not configured" });
+    }
+    await requireLimit3(deps, {
+      accountId: grant.accountId,
+      workspaceId,
+      action: "document:index",
+      quantity: 0
     });
-  }
-  return { state: DeviceEnrollmentState.enum.authorized, credentials };
-}
-async function buildEnrollmentCredentials(services, input) {
-  const { settings } = services;
-  const subjectPrefix = `agent.${input.workspaceId}.${input.agentId}`;
-  const nowSeconds = Math.floor(Date.now() / 1e3);
-  const exp = nowSeconds + ENROLLMENT_BEARER_TTL_SECONDS;
-  const bearer = await signEnrollmentBearer(input.secret, {
-    workspaceId: input.workspaceId,
-    agentId: input.agentId,
-    enrollmentId: input.agentId,
-    subjectPrefix,
-    exp
-  });
-  const natsUrls = settings.selfhostedNatsUrl ? [settings.selfhostedNatsUrl] : [];
-  const relayTokenSecret = resolveRelayTokenSecret(settings);
-  const relayToken = relayTokenSecret ? await signRelayToken(relayTokenSecret, {
-    workspaceId: input.workspaceId,
-    agentId: input.agentId,
-    exp: nowSeconds + RELAY_TOKEN_TTL_SECONDS
-  }) : "";
-  return {
-    agentId: input.agentId,
-    workspaceId: input.workspaceId,
-    bearer,
-    subjectPrefix,
-    natsUrls,
-    // Hand the agent the canonical `/stream` dial base, NOT the raw configured URL.
-    // The agent's relay producer appends only its routing query and assumes the base
-    // already carries the relay's `/stream` route; a path-less base 400s the dial and
-    // makes the terminal/desktop streams unreachable.
-    relayUrl: relayDialBaseFromSettings(settings),
-    relayToken,
-    // M-AUTH closes the placeholder: there is NO per-machine NATS Account creds
-    // file. The agent presents the BEARER as the NATS connect auth-token; the
-    // server's auth-callout responder validates it and mints a workspace-scoped
-    // user JWT. We echo the bearer here so a consumer reading this (vestigial) field
-    // as the connect credential still works — the value IS the bearer.
-    natsAccountCreds: bearer,
-    updatePublicKey: settings.agentUpdatePublicKey ?? "",
-    consentedWholeMachine: true,
-    consentedScreenControl: input.consentedScreenControl
-  };
-}
-
-// src/routes/enrollments.ts
-function registerEnrollmentRoutes(app, deps) {
-  const { settings, db } = deps;
-  function assertSelfhostedEnabled() {
-    if (!settings.sandboxSelfhostedEnabled) {
-      throw new HTTPException10(404, {
-        message: "selfhosted enrollment is not enabled for this deployment"
+    const payload = AddDocumentRequest.parse(await c.req.json());
+    try {
+      const document = await addDocumentToBase(db, {
+        ...payload,
+        accountId: grant.accountId,
+        workspaceId,
+        baseId: c.req.param("baseId"),
+        createdBy: grant.subjectId,
+        access: { viewerSubjectId: grant.subjectId }
       });
-    }
-  }
-  const startLimiter = new TokenBucket({ capacity: 10, refillPerSecond: 0.5 });
-  const pollLimiter = new TokenBucket({ capacity: 60, refillPerSecond: 2 });
-  const lookupLimiter = new TokenBucket({ capacity: 30, refillPerSecond: 1 });
-  const exchangeLimiter = new TokenBucket({ capacity: 20, refillPerSecond: 0.5 });
-  function rateLimit(c, limiter) {
-    const ip = clientIp(c);
-    if (!limiter.take(ip)) {
-      throw new HTTPException10(429, { message: "too many requests; slow down" });
-    }
-  }
-  app.post("/v1/enrollments/device/start", async (c) => {
-    assertSelfhostedEnabled();
-    rateLimit(c, startLimiter);
-    const parsed = DeviceEnrollmentStartRequest.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid device-start request" });
-    }
-    const body = parsed.data;
-    const workspace = await getWorkspace(db, body.workspaceId);
-    if (!workspace) {
-      throw new HTTPException10(404, { message: "workspace not found" });
-    }
-    const result = await startDeviceEnrollment(
-      { db, settings },
-      {
-        accountId: workspace.accountId,
-        workspaceId: workspace.id,
-        publicKey: body.publicKey,
-        os: body.os,
-        arch: body.arch,
-        machineName: body.machineName ?? null,
-        canOfferDisplay: body.canOfferDisplay,
-        requestsScreenControl: body.requestsScreenControl,
-        // The approve page is served at the SAME origin as this request.
-        verificationOrigin: new URL(c.req.url).origin
+      const wasCreated = document.status === "queued" && document.chunkCount === 0 && document.error === null;
+      const indexed = document.status === "ready" ? document : await documentIndexer.indexDocument({
+        accountId: grant.accountId,
+        workspaceId,
+        documentId: document.id
+      }) ?? document;
+      if (indexed.status === "ready") {
+        await recordWorkspaceUsage3(deps, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          eventType: "document.indexed",
+          quantity: indexed.chunkCount,
+          unit: "chunk",
+          sourceResourceType: "document",
+          sourceResourceId: indexed.id,
+          idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`
+        });
       }
-    );
-    return c.json(result, 201);
-  });
-  app.post("/v1/enrollments/device/poll", async (c) => {
-    assertSelfhostedEnabled();
-    rateLimit(c, pollLimiter);
-    const parsed = DeviceEnrollmentPollRequest.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid device-poll request" });
+      return c.json(Document.parse(indexed), wasCreated ? 201 : 200);
+    } catch (error) {
+      throw documentHttpException(error);
     }
-    const result = await pollDeviceEnrollment(
-      { db, settings },
-      { deviceCode: parsed.data.deviceCode }
+  });
+  app.get("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    return c.json(
+      (await listDocuments(db, workspaceId, c.req.param("baseId"), {
+        viewerSubjectId: grant.subjectId
+      })).map((document) => Document.parse(document))
     );
-    return c.json(result, 200);
   });
-  app.post("/v1/enrollments/device/lookup", async (c) => {
-    assertSelfhostedEnabled();
-    rateLimit(c, lookupLimiter);
-    const parsed = DeviceEnrollmentLookupRequest.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid device-lookup request" });
-    }
-    const record3 = await lookupDeviceEnrollment(
-      { db, settings },
-      { userCode: parsed.data.userCode }
-    );
-    if (!record3) {
-      throw new HTTPException10(404, { message: "no pending enrollment for that code" });
-    }
-    try {
-      await requireAccessGrant5(c, deps, record3.workspaceId, "enrollments:read");
-    } catch {
-      throw new HTTPException10(404, { message: "no pending enrollment for that code" });
-    }
-    return c.json(DeviceEnrollmentLookupResponse.parse(toLookupResponse(record3)), 200);
-  });
-  app.post("/v1/enrollments/token/exchange", async (c) => {
-    assertSelfhostedEnabled();
-    rateLimit(c, exchangeLimiter);
-    const parsed = EnrollTokenExchangeRequest.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid enroll-token-exchange request" });
+  app.delete(
+    "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+      try {
+        await deleteDocumentFromBase(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          baseId: c.req.param("baseId"),
+          documentId: c.req.param("documentId"),
+          access: { viewerSubjectId: grant.subjectId }
+        });
+        return c.body(null, 204);
+      } catch (error) {
+        if (error instanceof HTTPException10) {
+          throw error;
+        }
+        throw documentHttpException(error);
+      }
     }
-    const body = parsed.data;
-    const result = await exchangeEnrollToken(
-      { db, settings },
-      {
-        token: body.token,
-        publicKey: body.publicKey,
-        os: body.os,
-        arch: body.arch,
-        machineName: body.machineName ?? null,
-        canOfferDisplay: body.canOfferDisplay
+  );
+  app.post(
+    "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId/reindex",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+      if (!objectStorage) {
+        throw new HTTPException10(503, { message: "object storage is not configured" });
       }
-    );
-    if (!result.ok) {
-      if (result.reason === "disabled") {
-        throw new HTTPException10(503, { message: "enrollment credential plane is not configured" });
+      await requireLimit3(deps, {
+        accountId: grant.accountId,
+        workspaceId,
+        action: "document:index",
+        quantity: 0
+      });
+      try {
+        const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
+          viewerSubjectId: grant.subjectId
+        });
+        if (!document) {
+          throw new HTTPException10(404, { message: "document not found" });
+        }
+        if (document.status !== "failed") {
+          throw new HTTPException10(422, { message: "only failed documents can be retried" });
+        }
+        if (document.baseId !== c.req.param("baseId")) {
+          throw new HTTPException10(404, { message: "document not found" });
+        }
+        const queued = await queueDocumentForReindex(db, workspaceId, document.id, {
+          viewerSubjectId: grant.subjectId
+        });
+        const indexed = await documentIndexer.indexDocument({
+          accountId: grant.accountId,
+          workspaceId,
+          documentId: document.id
+        }) ?? queued;
+        if (indexed.status === "ready") {
+          await recordWorkspaceUsage3(deps, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            eventType: "document.indexed",
+            quantity: indexed.chunkCount,
+            unit: "chunk",
+            sourceResourceType: "document",
+            sourceResourceId: indexed.id,
+            idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`
+          });
+        }
+        return c.json(Document.parse(indexed));
+      } catch (error) {
+        if (error instanceof HTTPException10) {
+          throw error;
+        }
+        throw documentHttpException(error);
       }
-      throw new HTTPException10(401, { message: "invalid or expired enroll token" });
     }
-    return c.json(EnrollTokenExchangeResponse.parse({ credentials: result.credentials }), 201);
+  );
+  app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/search", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const payload = DocumentSearchRequest.parse(await c.req.json());
+    const base = await getDocumentBase(db, workspaceId, c.req.param("baseId"));
+    if (!base) {
+      throw new HTTPException10(404, { message: "document base not found" });
+    }
+    return c.json({
+      results: await searchDocuments2(
+        db,
+        {
+          workspaceId,
+          baseIds: [base.id],
+          query: payload.query,
+          limit: payload.limit,
+          mode: payload.mode,
+          sourceKinds: payload.sourceKinds,
+          aclTags: payload.aclTags,
+          access: { viewerSubjectId: grant.subjectId }
+        },
+        getDocumentServices()
+      )
+    });
   });
-  app.post("/v1/workspaces/:workspaceId/enrollments/device/approve", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/knowledge/search", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(c, deps, workspaceId, "enrollments:manage");
-    assertSelfhostedEnabled();
-    const parsed = DeviceEnrollmentApproveRequest.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid device-approve request" });
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const payload = DocumentSearchRequest.parse(await c.req.json());
+    return c.json({
+      results: await searchDocuments2(
+        db,
+        {
+          workspaceId,
+          query: payload.query,
+          baseIds: payload.baseIds,
+          limit: payload.limit,
+          mode: payload.mode,
+          sourceKinds: payload.sourceKinds,
+          aclTags: payload.aclTags,
+          access: { viewerSubjectId: grant.subjectId }
+        },
+        getDocumentServices()
+      )
+    });
+  });
+  app.post("/v1/workspaces/:workspaceId/knowledge/drops", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    if (!objectStorage) {
+      throw new HTTPException10(503, { message: "object storage is not configured" });
     }
-    const body = parsed.data;
-    const approved = await approveDeviceEnrollment(
-      { db, settings },
-      {
+    await requireLimit3(deps, {
+      accountId: grant.accountId,
+      workspaceId,
+      action: "document:index",
+      quantity: 0
+    });
+    const payload = CreateKnowledgeDropRequest.parse(await c.req.json());
+    try {
+      let fileId;
+      if (payload.text !== void 0) {
+        const bytes = new TextEncoder().encode(payload.text);
+        await requireLimit3(deps, {
+          accountId: grant.accountId,
+          workspaceId,
+          action: "file:upload",
+          quantity: bytes.length
+        });
+        if (bytes.length > objectStorage.maxSinglePutSizeBytes) {
+          throw new HTTPException10(413, {
+            message: `drop exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes`
+          });
+        }
+        const filename = dropFilename(payload.filename ?? payload.title);
+        const newFileId = crypto.randomUUID();
+        const safeFilename = sanitizeFilename(filename);
+        const objectKey = `workspaces/${workspaceId}/files/${newFileId}/original/${safeFilename}`;
+        const upload = await createFileUpload2(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          fileId: newFileId,
+          filename,
+          safeFilename,
+          contentType: "text/plain; charset=utf-8",
+          sizeBytes: bytes.length,
+          sha256: null,
+          bucket: objectStorage.bucket,
+          objectKey,
+          expiresAt: new Date(Date.now() + 15 * 60 * 1e3)
+        });
+        await objectStorage.putObject({
+          key: objectKey,
+          contentType: "text/plain; charset=utf-8",
+          body: bytes
+        });
+        const file = await completeFileUpload2(db, workspaceId, upload.uploadId);
+        await recordWorkspaceUsage3(deps, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          eventType: "file.uploaded",
+          quantity: file.sizeBytes,
+          unit: "byte",
+          sourceResourceType: "file",
+          sourceResourceId: file.id,
+          idempotencyKey: `file.uploaded:${workspaceId}:${file.id}`
+        });
+        fileId = file.id;
+      } else {
+        fileId = payload.fileId;
+      }
+      const defaultBase = await ensureDefaultBase(db, {
+        accountId: grant.accountId,
+        workspaceId
+      });
+      const document = await addDocumentToBase(db, {
+        fileId,
+        ...payload.title ? { title: payload.title } : {},
+        ...payload.visibility ? { visibility: payload.visibility } : {},
+        ...payload.agentAccess !== void 0 ? { agentAccess: payload.agentAccess } : {},
         accountId: grant.accountId,
         workspaceId,
-        userCode: body.userCode,
-        allowScreenControl: body.allowScreenControl,
-        // The LOUD consent record: WHO consented (the authenticated subject + label).
-        approvedBySubjectId: grant.subjectId,
-        approvedBySubjectLabel: grant.subjectLabel ?? null
+        baseId: defaultBase.id,
+        createdBy: grant.subjectId,
+        curationStatus: "pending",
+        access: { viewerSubjectId: grant.subjectId }
+      });
+      const wasCreated = document.status === "queued" && document.chunkCount === 0 && document.error === null;
+      const indexed = document.status === "ready" ? document : await documentIndexer.indexDocument({
+        accountId: grant.accountId,
+        workspaceId,
+        documentId: document.id
+      }) ?? document;
+      if (indexed.status === "ready") {
+        await recordWorkspaceUsage3(deps, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          eventType: "document.indexed",
+          quantity: indexed.chunkCount,
+          unit: "chunk",
+          sourceResourceType: "document",
+          sourceResourceId: indexed.id,
+          idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`
+        });
       }
-    );
-    if (!approved) {
-      throw new HTTPException10(404, { message: "no pending enrollment for that code" });
+      return c.json(Document.parse(indexed), wasCreated ? 201 : 200);
+    } catch (error) {
+      if (error instanceof HTTPException10) {
+        throw error;
+      }
+      throw documentHttpException(error);
     }
-    return c.json(
-      DeviceEnrollmentApproveResponse.parse({
-        approved: true,
-        enrollmentId: approved.enrollmentId,
-        sandboxId: approved.sandboxId,
-        allowScreenControl: approved.allowScreenControl
-      }),
-      201
-    );
   });
-  app.post("/v1/workspaces/:workspaceId/enrollments/device/deny", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/documents/:documentId/move", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(c, deps, workspaceId, "enrollments:manage");
-    assertSelfhostedEnabled();
-    const parsed = DeviceEnrollmentDenyRequest.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid device-deny request" });
-    }
-    const result = await denyDeviceEnrollment(
-      { db, settings },
-      {
-        accountId: grant.accountId,
-        workspaceId,
-        userCode: parsed.data.userCode
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    const payload = MoveDocumentRequest.parse(await c.req.json().catch(() => ({})));
+    try {
+      const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
+        viewerSubjectId: grant.subjectId
+      });
+      if (!document) {
+        throw new HTTPException10(404, { message: "document not found" });
       }
-    );
-    return c.json(DeviceEnrollmentDenyResponse.parse({ denied: result.denied }), 200);
+      return c.json(
+        Document.parse(
+          await moveDocumentToBase(db, {
+            accountId: grant.accountId,
+            workspaceId,
+            documentId: document.id,
+            targetBaseId: payload.targetBaseId ?? null,
+            access: { viewerSubjectId: grant.subjectId }
+          })
+        )
+      );
+    } catch (error) {
+      if (error instanceof HTTPException10) {
+        throw error;
+      }
+      throw documentHttpException(error);
+    }
   });
-  app.post("/v1/workspaces/:workspaceId/enrollments/token", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(c, deps, workspaceId, "enrollments:manage");
-    assertSelfhostedEnabled();
-    const parsed = MintEnrollTokenRequest.safeParse(await c.req.json().catch(() => ({})));
+    await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const parsed = KnowledgeMemorySearchRequest.safeParse({
+      query: c.req.query("query") || void 0,
+      status: c.req.query("status") || void 0,
+      kind: c.req.query("kind") || void 0,
+      scope: c.req.query("scope") || void 0,
+      limit: c.req.query("limit") ? Number(c.req.query("limit")) : void 0
+    });
     if (!parsed.success) {
-      throw new HTTPException10(400, { message: "invalid mint-enroll-token request" });
+      throw new HTTPException10(400, { message: "invalid knowledge memory query parameters" });
     }
-    const minted = await mintEnrollToken(
-      { db, settings },
-      {
-        accountId: grant.accountId,
-        workspaceId,
-        allowScreenControl: parsed.data.allowScreenControl
-      }
+    return c.json(
+      (await listKnowledgeMemories2(db, workspaceId, parsed.data)).map(
+        (memory) => KnowledgeMemory.parse(memory)
+      )
     );
-    if (!minted) {
-      throw new HTTPException10(503, { message: "enrollment credential plane is not configured" });
+  });
+  app.get("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const memory = await getKnowledgeMemory(db, workspaceId, c.req.param("memoryId"));
+    if (!memory) {
+      throw new HTTPException10(404, { message: "knowledge memory not found" });
     }
-    return c.json(MintEnrollTokenResponse.parse(minted), 201);
+    return c.json(KnowledgeMemory.parse(memory));
   });
-  app.get("/v1/workspaces/:workspaceId/enrollments", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/knowledge/memories/search", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant5(c, deps, workspaceId, "enrollments:read");
-    assertSelfhostedEnabled();
-    const statusFilter = c.req.query("status");
-    const rows = await listEnrollments(
+    await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const parsed = WorkspaceMemorySearchRequest.safeParse(await c.req.json());
+    if (!parsed.success) {
+      throw new HTTPException10(400, { message: "invalid workspace memory search request" });
+    }
+    const results = await searchWorkspaceMemories2(
       db,
       workspaceId,
-      statusFilter === "active" ? { status: "active" } : {}
+      parsed.data,
+      getDocumentServices().embedder
     );
     return c.json(
-      ListEnrollmentsResponse.parse({
-        enrollments: rows.map(
-          (row) => EnrollmentSummary.parse({
-            id: row.id,
-            pubkey: row.pubkey,
-            exposure: row.exposure,
-            hasDisplay: row.hasDisplay,
-            desktopUnavailableReason: row.desktopUnavailableReason,
-            allowScreenControl: row.allowScreenControl,
-            status: row.status,
-            os: row.os,
-            arch: row.arch,
-            lastSeenAt: row.lastSeenAt,
-            createdAt: row.createdAt,
-            revokedAt: row.revokedAt
-          })
-        )
+      WorkspaceMemorySearchResponse.parse({
+        results: results.map((result) => ({
+          ...result,
+          memory: KnowledgeMemory.parse(result.memory)
+        }))
       })
     );
   });
-  app.post("/v1/workspaces/:workspaceId/enrollments/:enrollmentId/revoke", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(c, deps, workspaceId, "enrollments:manage");
-    assertSelfhostedEnabled();
-    const result = await revokeEnrollment(db, {
-      accountId: grant.accountId,
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    const parsedBody = CreateKnowledgeMemoryRequest.safeParse(await c.req.json());
+    if (!parsedBody.success) {
+      throw new HTTPException10(400, { message: "invalid knowledge memory request" });
+    }
+    const payload = parsedBody.data;
+    if (payload.status === "active") {
+      try {
+        const result = await saveWorkspaceMemory2(
+          db,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            text: payload.text,
+            kind: payload.kind,
+            confidence: payload.confidence,
+            pinned: payload.pinned,
+            replacesId: payload.replacesId ?? null,
+            metadata: payload.metadata,
+            origin: "human"
+          },
+          getDocumentServices().embedder
+        );
+        return c.json(KnowledgeMemory.parse(result.memory), 201);
+      } catch (error) {
+        throw documentHttpException(error);
+      }
+    }
+    return c.json(
+      KnowledgeMemory.parse(
+        await createKnowledgeMemory2(db, {
+          ...payload,
+          accountId: grant.accountId,
+          workspaceId
+        })
+      ),
+      201
+    );
+  });
+  app.patch("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    const payload = UpdateKnowledgeMemoryRequest.parse(await c.req.json());
+    const reviewedBy = payload.reviewedBy ?? (payload.status === "approved" || payload.status === "rejected" ? grant.subjectLabel ?? grant.subjectId : void 0);
+    try {
+      return c.json(
+        KnowledgeMemory.parse(
+          await updateKnowledgeMemory(
+            db,
+            workspaceId,
+            c.req.param("memoryId"),
+            {
+              ...payload,
+              ...reviewedBy ? { reviewedBy } : {}
+            },
+            getDocumentServices().embedder
+          )
+        )
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+  app.all("/v1/workspaces/:workspaceId/mcp/docs", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:search");
+    const sessionId = typeof grant.metadata?.sessionId === "string" ? grant.metadata.sessionId : void 0;
+    const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+    const server = buildDocumentsMcpServer(
+      db,
+      grant.accountId,
       workspaceId,
-      enrollmentId: c.req.param("enrollmentId")
-    });
-    return c.json(RevokeEnrollmentResponse.parse(result));
+      getDocumentServices(),
+      { createdBySessionId: sessionId, viewerSubjectId: grant.subjectId }
+    );
+    await server.connect(transport);
+    return await transport.handleRequest(c.req.raw);
   });
 }
-function clientIp(c) {
-  const xff = c.req.header("x-forwarded-for");
-  if (xff) {
-    const first = xff.split(",")[0]?.trim();
-    if (first) return first;
-  }
-  return c.req.header("x-real-ip")?.trim() || "unknown";
+function dropFilename(preferred) {
+  const stem = (preferred ?? "").trim() || `note-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
+  return /\.[A-Za-z0-9]{1,8}$/.test(stem) ? stem : `${stem}.txt`;
 }
-var TokenBucket = class {
-  capacity;
-  refillPerSecond;
-  buckets = /* @__PURE__ */ new Map();
-  constructor(options) {
-    this.capacity = options.capacity;
-    this.refillPerSecond = options.refillPerSecond;
+function documentHttpException(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("not found")) {
+    return new HTTPException10(404, { message });
   }
-  take(key, now = Date.now()) {
-    const bucket = this.buckets.get(key) ?? { tokens: this.capacity, updatedAt: now };
-    const elapsedSeconds = Math.max(0, (now - bucket.updatedAt) / 1e3);
-    bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsedSeconds * this.refillPerSecond);
-    bucket.updatedAt = now;
-    if (bucket.tokens >= this.capacity && this.buckets.size > 1e4) {
-      this.buckets.delete(key);
-    }
-    if (bucket.tokens < 1) {
-      this.buckets.set(key, bucket);
-      return false;
-    }
-    bucket.tokens -= 1;
-    this.buckets.set(key, bucket);
-    return true;
+  if (message.includes("already exists")) {
+    return new HTTPException10(409, { message });
   }
-};
+  if (message.includes("no suggested base")) {
+    return new HTTPException10(422, { message });
+  }
+  if (message.includes("pending") || message.includes("failed") || message.includes("deleted")) {
+    return new HTTPException10(422, { message });
+  }
+  if (message.includes("too long") || message.includes("visible memory is full") || message.includes("empty after sanitization") || message.includes("does not match") || message.includes("Ambiguous memory id")) {
+    return new HTTPException10(400, { message });
+  }
+  return new HTTPException10(500, { message });
+}
 
-// src/routes/machines.ts
+// src/routes/enrollments.ts
 import {
-  MachineMetricsSeriesResponse,
-  MachinesResponse,
-  SwapActiveSandboxRequest,
-  SwapActiveSandboxResponse
+  DeviceEnrollmentApproveRequest,
+  DeviceEnrollmentApproveResponse,
+  DeviceEnrollmentDenyRequest,
+  DeviceEnrollmentDenyResponse,
+  DeviceEnrollmentLookupRequest,
+  DeviceEnrollmentLookupResponse,
+  DeviceEnrollmentPollRequest,
+  DeviceEnrollmentStartRequest,
+  EnrollmentSummary,
+  EnrollTokenExchangeRequest,
+  EnrollTokenExchangeResponse,
+  ListEnrollmentsResponse,
+  MintEnrollTokenRequest,
+  MintEnrollTokenResponse,
+  RevokeEnrollmentResponse
 } from "@opengeni/contracts";
-import { getEnrollment as getEnrollment2, readMachineMetricsSeries, requireSession as requireSession3 } from "@opengeni/db";
+import { getWorkspace, listEnrollments, revokeEnrollment } from "@opengeni/db";
 import { HTTPException as HTTPException11 } from "hono/http-exception";
 import { requireAccessGrant as requireAccessGrant6 } from "@opengeni/core";
-import { buildFleetContextForSession as buildFleetContextForSession2, swapActiveSandbox as swapActiveSandbox2 } from "@opengeni/core";
 
-// src/sandbox/machines.ts
+// src/sandbox/enrollment.ts
+import { randomBytes as randomBytes2 } from "crypto";
 import {
-  getSession as getSession3,
-  listEnrollments as listEnrollments2,
-  listSandboxes,
-  readActiveSandbox,
-  readLease as readLease2,
-  readMachineMetricsLatestForWorkspace
-} from "@opengeni/db";
-import { MachineView, MetricSample } from "@opengeni/contracts";
+  resolveEnrollmentSigningSecret,
+  resolveRelayTokenSecret
+} from "@opengeni/config";
 import {
-  NatsControlRpc as NatsControlRpc2,
-  selfhostedLiveness,
-  SelfhostedSession
-} from "@opengeni/runtime/sandbox";
-import { relayConfigFromSettings as relayConfigFromSettings2 } from "@opengeni/core";
-var PROBE_TIMEOUT_MS = 5e3;
-function controlRpc2(bus) {
-  return new NatsControlRpc2(async () => {
-    if (!bus) {
-      return null;
-    }
-    return bus.getRequestConnection();
-  });
+  DeviceEnrollmentState,
+  signEnrollmentBearer,
+  signEnrollToken,
+  signRelayToken,
+  verifyEnrollToken
+} from "@opengeni/contracts";
+import {
+  approveDeviceEnrollmentRequest,
+  consumeDeviceEnrollmentRequest,
+  createDeviceEnrollmentRequest,
+  denyDeviceEnrollmentRequest,
+  finalizeEnrollmentByToken,
+  getDeviceEnrollmentRequestByDeviceCode,
+  getEnrollment,
+  getPendingDeviceEnrollmentRequestByUserCode,
+  getPendingDeviceEnrollmentRequestByUserCodeGlobal
+} from "@opengeni/db";
+import { relayDialBaseFromSettings } from "@opengeni/core";
+var DEVICE_CODE_TTL_SECONDS = 600;
+var DEVICE_POLL_INTERVAL_SECONDS = 5;
+var ENROLLMENT_BEARER_TTL_SECONDS = 30 * 24 * 3600;
+var RELAY_TOKEN_TTL_SECONDS = 30 * 24 * 3600;
+var ENROLL_TOKEN_TTL_SECONDS = 3600;
+function mintDeviceCode() {
+  return randomBytes2(32).toString("base64url");
 }
-function metricRowToSample(row) {
-  return MetricSample.parse({
-    cpuPct: row.cpuPercent ?? 0,
-    load1: row.load1 ?? 0,
-    load5: row.load5 ?? 0,
-    load15: row.load15 ?? 0,
-    memUsedBytes: row.memUsedBytes ?? 0,
-    memTotalBytes: row.memTotalBytes ?? 0,
-    diskUsedBytes: row.diskUsedBytes ?? 0,
-    diskTotalBytes: row.diskTotalBytes ?? 0,
-    gpuUtilPct: row.gpuUtilPercent,
-    gpuMemBytes: row.gpuMemUsedBytes,
-    runQueue: row.contention ?? 0,
-    sampledAt: row.sampledAt
-  });
+var USER_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+function mintUserCode() {
+  const bytes = randomBytes2(8);
+  let out = "";
+  for (let i = 0; i < 8; i += 1) {
+    out += USER_CODE_ALPHABET[bytes[i] % USER_CODE_ALPHABET.length];
+  }
+  return `${out.slice(0, 4)}-${out.slice(4, 8)}`;
 }
-async function probeEnrollment(services, workspaceId, enrollment) {
-  const { settings, bus } = services;
-  let probeResponded = false;
-  if (enrollment.status === "active") {
-    const session = new SelfhostedSession({
-      workspaceId,
-      agentId: enrollment.id,
-      controlRpc: controlRpc2(bus),
-      relay: relayConfigFromSettings2(settings),
-      timeoutMs: PROBE_TIMEOUT_MS
-    });
+async function startDeviceEnrollment(services, input) {
+  const { db } = services;
+  const expiresAt = new Date(Date.now() + DEVICE_CODE_TTL_SECONDS * 1e3);
+  let request;
+  let lastError;
+  for (let attempt = 0; attempt < 5 && !request; attempt += 1) {
+    const deviceCode = mintDeviceCode();
+    const userCode = mintUserCode();
     try {
-      probeResponded = await session.ping();
-    } catch {
-      probeResponded = false;
+      request = await createDeviceEnrollmentRequest(db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        deviceCode,
+        userCode,
+        pubkey: input.publicKey,
+        os: input.os,
+        arch: input.arch,
+        machineName: input.machineName ?? null,
+        requestedExposure: "whole-machine",
+        canOfferDisplay: input.canOfferDisplay,
+        requestsScreenControl: input.requestsScreenControl,
+        expiresAt
+      });
+    } catch (error) {
+      lastError = error;
     }
   }
-  const derived = selfhostedLiveness({
-    enrollment: {
-      status: enrollment.status,
-      exposure: enrollment.exposure,
-      allowScreenControl: enrollment.allowScreenControl,
-      hasDisplay: enrollment.hasDisplay,
-      lastSeenAt: enrollment.lastSeenAt,
-      wentOfflineAt: enrollment.wentOfflineAt,
-      wentOfflineReason: enrollment.wentOfflineReason
-    },
-    probeResponded
-  });
-  return { state: derived.state, consented: derived.consented, hasDisplay: derived.hasDisplay };
-}
-function machineStateFor(liveness, hasDisplay) {
-  if (liveness !== "online") {
-    return liveness;
-  }
-  if (!hasDisplay) {
-    return "display_unavailable";
+  if (!request) {
+    throw lastError instanceof Error ? lastError : new Error("failed to start device enrollment");
   }
-  return "online";
+  const base = input.verificationOrigin.replace(/\/$/, "");
+  const verificationUri = `${base}/device`;
+  const verificationUriComplete = `${verificationUri}?user_code=${encodeURIComponent(request.userCode)}`;
+  return {
+    deviceCode: request.deviceCode,
+    userCode: request.userCode,
+    verificationUri,
+    verificationUriComplete,
+    intervalSeconds: DEVICE_POLL_INTERVAL_SECONDS,
+    expiresInSeconds: DEVICE_CODE_TTL_SECONDS
+  };
 }
-async function listMachines(services, input) {
+async function approveDeviceEnrollment(services, input) {
   const { db } = services;
-  const { workspaceId } = input;
-  let activeSandboxId = null;
-  let activeEpoch = 0;
-  let session = null;
-  if (input.sessionId) {
-    session = await getSession3(db, workspaceId, input.sessionId);
-    if (session) {
-      const pointer = await readActiveSandbox(db, workspaceId, input.sessionId);
-      activeSandboxId = pointer?.activeSandboxId ?? null;
-      activeEpoch = pointer?.activeEpoch ?? 0;
-    }
+  const pending = await getPendingDeviceEnrollmentRequestByUserCode(
+    db,
+    input.workspaceId,
+    input.userCode
+  );
+  if (!pending) {
+    return null;
   }
-  const machines = [];
-  if (session) {
-    const groupActive = activeSandboxId === null;
-    const groupLease = await readLease2(db, workspaceId, session.sandboxGroupId);
-    machines.push(
-      MachineView.parse({
-        sandboxId: session.sandboxGroupId,
-        enrollmentId: null,
-        name: "session sandbox",
-        kind: session.sandboxBackend === "selfhosted" ? "selfhosted" : "modal",
-        state: "online",
-        active: groupActive,
-        isSessionGroup: true,
-        workspaceGeneration: groupLease?.workspaceGeneration ?? null,
-        archiveGeneration: groupLease?.archiveGeneration ?? null,
-        archiveComplete: groupLease?.archiveComplete ?? false,
-        // The Modal group box is a cloud Linux box; its precise OS/arch is not
-        // surfaced as a metric, so the dashboard shows the canonical linux/x86_64.
-        os: "linux",
-        arch: "x86_64",
-        hasDisplay: false,
-        desktopUnavailableReason: null,
-        allowScreenControl: false,
-        sharedSessionCount: 1,
-        lastSeenAt: null,
-        metrics: null
-      })
-    );
+  const sandboxName = (pending.machineName?.trim() || `${pending.os} machine`).slice(0, 256);
+  const result = await approveDeviceEnrollmentRequest(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    requestId: pending.id,
+    allowScreenControl: input.allowScreenControl,
+    approvedBySubjectId: input.approvedBySubjectId,
+    approvedBySubjectLabel: input.approvedBySubjectLabel ?? null,
+    sandboxName
+  });
+  if (!result.approved || !result.enrollment || !result.sandbox) {
+    return null;
   }
-  const [sandboxes, enrollments, metricsByEnrollment] = await Promise.all([
-    listSandboxes(db, workspaceId),
-    listEnrollments2(db, workspaceId),
-    readMachineMetricsLatestForWorkspace(db, workspaceId)
-  ]);
-  const enrollmentById = new Map(enrollments.map((e) => [e.id, e]));
-  const machineViews = await Promise.all(
-    sandboxes.map(async (sandbox) => {
-      if (sandbox.kind !== "selfhosted" || !sandbox.enrollmentId) {
-        return null;
-      }
-      const enrollment = enrollmentById.get(sandbox.enrollmentId) ?? null;
-      if (!enrollment) {
-        return null;
-      }
-      const [probe, lease] = await Promise.all([
-        probeEnrollment(services, workspaceId, enrollment),
-        readLease2(db, workspaceId, sandbox.id)
-      ]);
-      const state = machineStateFor(probe.state, probe.hasDisplay);
-      const sharedSessionCount = lease?.refcount ?? 0;
-      const metricsRow = metricsByEnrollment.get(enrollment.id) ?? null;
-      return MachineView.parse({
-        sandboxId: sandbox.id,
-        enrollmentId: enrollment.id,
-        name: sandbox.name,
-        kind: "selfhosted",
-        state,
-        active: activeSandboxId === sandbox.id,
-        isSessionGroup: false,
-        workspaceGeneration: null,
-        archiveGeneration: null,
-        archiveComplete: false,
-        os: enrollment.os,
-        arch: enrollment.arch,
-        hasDisplay: enrollment.hasDisplay,
-        desktopUnavailableReason: enrollment.desktopUnavailableReason,
-        allowScreenControl: enrollment.allowScreenControl,
-        sharedSessionCount,
-        lastSeenAt: enrollment.lastSeenAt,
-        metrics: metricsRow ? metricRowToSample(metricsRow) : null
-      });
-    })
+  return {
+    enrollmentId: result.enrollment.id,
+    sandboxId: result.sandbox.id,
+    allowScreenControl: result.enrollment.allowScreenControl
+  };
+}
+async function lookupDeviceEnrollment(services, input) {
+  const { db } = services;
+  return await getPendingDeviceEnrollmentRequestByUserCodeGlobal(db, input.userCode);
+}
+function toLookupResponse(record3) {
+  return {
+    workspaceId: record3.workspaceId,
+    userCode: record3.userCode,
+    machine: {
+      machineName: record3.machineName,
+      os: record3.os,
+      arch: record3.arch,
+      canOfferDisplay: record3.canOfferDisplay,
+      requestsScreenControl: record3.requestsScreenControl
+    },
+    expiresAt: record3.expiresAt
+  };
+}
+async function denyDeviceEnrollment(services, input) {
+  const { db } = services;
+  const pending = await getPendingDeviceEnrollmentRequestByUserCode(
+    db,
+    input.workspaceId,
+    input.userCode
   );
-  machines.push(...machineViews.filter((machine) => machine !== null));
-  return { activeSandboxId, activeEpoch, machines };
+  if (!pending) {
+    return { denied: false };
+  }
+  return await denyDeviceEnrollmentRequest(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    requestId: pending.id
+  });
 }
-
-// src/routes/machines.ts
-var SERIES_WINDOWS_MS = {
-  "15m": 15 * 6e4,
-  "1h": 60 * 6e4,
-  "6h": 6 * 60 * 6e4,
-  "24h": 24 * 60 * 6e4
-};
-var DEFAULT_SERIES_WINDOW_MS = SERIES_WINDOWS_MS["1h"];
-function registerMachineRoutes(app, deps) {
-  const { settings, db, bus } = deps;
-  function assertSelfhostedEnabled() {
-    if (!settings.sandboxSelfhostedEnabled) {
-      throw new HTTPException11(404, {
-        message: "selfhosted machines are not enabled for this deployment"
-      });
-    }
+async function mintEnrollToken(services, input) {
+  const { settings } = services;
+  const secret = resolveEnrollmentSigningSecret(settings);
+  if (!secret) {
+    return null;
   }
-  app.get("/v1/workspaces/:workspaceId/machines", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant6(c, deps, workspaceId, "enrollments:read");
-    assertSelfhostedEnabled();
-    const sessionId = c.req.query("sessionId") ?? null;
-    const response = await listMachines({ db, settings, bus }, { workspaceId, sessionId });
-    return c.json(MachinesResponse.parse(response));
+  const nowSeconds = Math.floor(Date.now() / 1e3);
+  const exp = nowSeconds + ENROLL_TOKEN_TTL_SECONDS;
+  const token = await signEnrollToken(secret, {
+    typ: "enroll",
+    workspaceId: input.workspaceId,
+    accountId: input.accountId,
+    allowScreenControl: input.allowScreenControl,
+    iat: nowSeconds,
+    exp
   });
-  app.get("/v1/workspaces/:workspaceId/machines/:enrollmentId/metrics/series", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant6(c, deps, workspaceId, "enrollments:read");
-    assertSelfhostedEnabled();
-    const enrollmentId = c.req.param("enrollmentId");
-    const enrollment = await getEnrollment2(db, workspaceId, enrollmentId);
-    if (!enrollment) {
-      throw new HTTPException11(404, { message: "machine not found in this workspace" });
-    }
-    const windowMs = SERIES_WINDOWS_MS[c.req.query("window") ?? ""] ?? DEFAULT_SERIES_WINDOW_MS;
-    const since = new Date(Date.now() - windowMs);
-    const rows = await readMachineMetricsSeries(db, { workspaceId, enrollmentId, since });
-    return c.json(
-      MachineMetricsSeriesResponse.parse({
-        samples: rows.map(metricRowToSample)
-      })
-    );
+  return {
+    token,
+    expiresAt: new Date(exp * 1e3).toISOString(),
+    expiresInSeconds: ENROLL_TOKEN_TTL_SECONDS
+  };
+}
+async function exchangeEnrollToken(services, input) {
+  const { db, settings } = services;
+  const secret = resolveEnrollmentSigningSecret(settings);
+  if (!secret) {
+    return { ok: false, reason: "disabled" };
+  }
+  const claims = await verifyEnrollToken(secret, input.token);
+  if (!claims) {
+    return { ok: false, reason: "invalid" };
+  }
+  const sandboxName = (input.machineName?.trim() || `${input.os} machine`).slice(0, 256);
+  const { enrollment } = await finalizeEnrollmentByToken(db, {
+    accountId: claims.accountId,
+    workspaceId: claims.workspaceId,
+    pubkey: input.publicKey,
+    hasDisplay: input.canOfferDisplay,
+    // The token's allowScreenControl is the AUTHORITATIVE consent (NOT the agent's
+    // requestsScreenControl) — it was baked in at mint by the authorizing user.
+    allowScreenControl: claims.allowScreenControl,
+    os: input.os,
+    arch: input.arch,
+    sandboxName
   });
-  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/active-sandbox", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant6(c, deps, workspaceId, "sessions:control");
-    assertSelfhostedEnabled();
-    const sessionId = c.req.param("sessionId");
-    const body = SwapActiveSandboxRequest.parse(await c.req.json());
-    const ctx = await buildFleetContextForSession2(deps, {
-      accountId: grant.accountId,
-      workspaceId,
-      sessionId
+  const credentials = await buildEnrollmentCredentials(services, {
+    secret,
+    workspaceId: claims.workspaceId,
+    agentId: enrollment.id,
+    consentedScreenControl: enrollment.allowScreenControl
+  });
+  return { ok: true, credentials };
+}
+async function pollDeviceEnrollment(services, input) {
+  const { db, settings } = services;
+  const request = await getDeviceEnrollmentRequestByDeviceCode(db, input.deviceCode);
+  if (!request) {
+    return { state: "expired" };
+  }
+  if (request.status === "denied") {
+    return { state: "denied" };
+  }
+  if (request.status === "pending") {
+    if (new Date(request.expiresAt).getTime() <= Date.now()) {
+      return { state: "expired" };
+    }
+    return { state: "pending" };
+  }
+  if (!request.enrollmentId) {
+    return { state: "expired" };
+  }
+  const secret = resolveEnrollmentSigningSecret(settings);
+  if (!secret) {
+    return { state: "disabled" };
+  }
+  const enrollment = await getEnrollment(db, request.workspaceId, request.enrollmentId);
+  if (!enrollment || enrollment.status !== "active") {
+    return { state: "denied" };
+  }
+  const credentials = await buildEnrollmentCredentials(services, {
+    secret,
+    workspaceId: request.workspaceId,
+    agentId: enrollment.id,
+    consentedScreenControl: enrollment.allowScreenControl
+  });
+  if (request.status === "approved") {
+    await consumeDeviceEnrollmentRequest(db, {
+      accountId: request.accountId,
+      workspaceId: request.workspaceId,
+      requestId: request.id
     });
-    const result = await swapActiveSandbox2(
-      {
-        db,
-        settings,
-        bus,
-        ensureSessionGroupReady: async (fleetCtx) => {
-          const session = await requireSession3(db, fleetCtx.workspaceId, fleetCtx.sessionId);
-          return await ensureSessionGroupReady(
-            { db, settings, bus },
-            {
-              accountId: fleetCtx.accountId,
-              workspaceId: fleetCtx.workspaceId,
-              session
-            }
-          );
-        }
-      },
-      ctx,
-      body.target
-    );
-    return c.json(SwapActiveSandboxResponse.parse(result));
+  }
+  return { state: DeviceEnrollmentState.enum.authorized, credentials };
+}
+async function buildEnrollmentCredentials(services, input) {
+  const { settings } = services;
+  const subjectPrefix = `agent.${input.workspaceId}.${input.agentId}`;
+  const nowSeconds = Math.floor(Date.now() / 1e3);
+  const exp = nowSeconds + ENROLLMENT_BEARER_TTL_SECONDS;
+  const bearer = await signEnrollmentBearer(input.secret, {
+    workspaceId: input.workspaceId,
+    agentId: input.agentId,
+    enrollmentId: input.agentId,
+    subjectPrefix,
+    exp
   });
+  const natsUrls = settings.selfhostedNatsUrl ? [settings.selfhostedNatsUrl] : [];
+  const relayTokenSecret = resolveRelayTokenSecret(settings);
+  const relayToken = relayTokenSecret ? await signRelayToken(relayTokenSecret, {
+    workspaceId: input.workspaceId,
+    agentId: input.agentId,
+    exp: nowSeconds + RELAY_TOKEN_TTL_SECONDS
+  }) : "";
+  return {
+    agentId: input.agentId,
+    workspaceId: input.workspaceId,
+    bearer,
+    subjectPrefix,
+    natsUrls,
+    // Hand the agent the canonical `/stream` dial base, NOT the raw configured URL.
+    // The agent's relay producer appends only its routing query and assumes the base
+    // already carries the relay's `/stream` route; a path-less base 400s the dial and
+    // makes the terminal/desktop streams unreachable.
+    relayUrl: relayDialBaseFromSettings(settings),
+    relayToken,
+    // M-AUTH closes the placeholder: there is NO per-machine NATS Account creds
+    // file. The agent presents the BEARER as the NATS connect auth-token; the
+    // server's auth-callout responder validates it and mints a workspace-scoped
+    // user JWT. We echo the bearer here so a consumer reading this (vestigial) field
+    // as the connect credential still works — the value IS the bearer.
+    natsAccountCreds: bearer,
+    updatePublicKey: settings.agentUpdatePublicKey ?? "",
+    consentedWholeMachine: true,
+    consentedScreenControl: input.consentedScreenControl
+  };
 }
 
-// src/routes/environments.ts
-import {
-  CreateVariableSetRequest,
-  SetVariableSetVariableRequest,
-  UpdateVariableSetRequest,
-  VariableSetVariableName as VariableSetVariableName2
-} from "@opengeni/contracts";
-import {
-  countActiveSessionsUsingVariableSet,
-  countScheduledTasksUsingVariableSet,
-  countVariableSets as countVariableSets2,
-  createVariableSet as createVariableSet2,
-  deleteVariableSet,
-  deleteVariableSetVariable,
-  encryptVariableSetValue as encryptVariableSetValue2,
-  getVariableSetByName as getVariableSetByName2,
-  listVariableSets as listVariableSets2,
-  setVariableSetVariable as setVariableSetVariable2,
-  updateVariableSet
-} from "@opengeni/db";
-import { HTTPException as HTTPException12 } from "hono/http-exception";
-import { requireAccessGrant as requireAccessGrant7 } from "@opengeni/core";
-import {
-  assertAllowedVariableSetVariableName as assertAllowedVariableSetVariableName2,
-  MAX_ENVIRONMENTS_PER_WORKSPACE as MAX_ENVIRONMENTS_PER_WORKSPACE2,
-  MAX_VARIABLES_PER_ENVIRONMENT as MAX_VARIABLES_PER_ENVIRONMENT2,
-  recordVariableSetAuditEvent as recordVariableSetAuditEvent2,
-  requireVariableSetEncryption as requireVariableSetEncryption2,
-  requireVariableSetForApi
-} from "@opengeni/core";
-function registerVariableSetRoutes(app, deps) {
+// src/routes/enrollments.ts
+function registerEnrollmentRoutes(app, deps) {
   const { settings, db } = deps;
-  const prefixes = [
-    "/v1/workspaces/:workspaceId/variable-sets",
-    "/v1/workspaces/:workspaceId/environments"
-  ];
-  for (const prefix of prefixes) {
-    app.get(`${prefix}`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      await requireAccessGrant7(c, deps, workspaceId, "variable-sets:use");
-      return c.json(await listVariableSets2(db, workspaceId));
-    });
-    app.post(`${prefix}`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant7(c, deps, workspaceId, "variable-sets:manage");
-      const key = requireVariableSetEncryption2(settings);
-      const payload = CreateVariableSetRequest.parse(await c.req.json());
-      const name = trimmedVariableSetName(payload.name);
-      if (payload.variables.length > MAX_VARIABLES_PER_ENVIRONMENT2) {
-        throw new HTTPException12(422, {
-          message: `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT2} variables`
-        });
-      }
-      const variableNames = /* @__PURE__ */ new Set();
-      for (const variable of payload.variables) {
-        assertAllowedVariableSetVariableName2(variable.name);
-        if (variableNames.has(variable.name)) {
-          throw new HTTPException12(422, {
-            message: `duplicate variable set variable name: ${variable.name}`
-          });
-        }
-        variableNames.add(variable.name);
-      }
-      if (await countVariableSets2(db, workspaceId) >= MAX_ENVIRONMENTS_PER_WORKSPACE2) {
-        throw new HTTPException12(422, {
-          message: `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE2} variable sets`
-        });
-      }
-      if (await getVariableSetByName2(db, workspaceId, name)) {
-        throw new HTTPException12(409, { message: `variable set name is already in use: ${name}` });
-      }
-      const created = await createVariableSet2(db, {
-        accountId: grant.accountId,
-        workspaceId,
-        name,
-        description: payload.description ?? null,
-        variables: payload.variables.map((variable) => ({
-          name: variable.name,
-          valueEncrypted: encryptVariableSetValue2(key, variable.value)
-        }))
-      });
-      await recordVariableSetAuditEvent2(db, {
-        grant,
-        action: "variable_set.created",
-        variableSetId: created.id
+  function assertSelfhostedEnabled() {
+    if (!settings.sandboxSelfhostedEnabled) {
+      throw new HTTPException11(404, {
+        message: "selfhosted enrollment is not enabled for this deployment"
       });
-      return c.json(created, 201);
-    });
-    app.get(`${prefix}/:variableSetId`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      await requireAccessGrant7(c, deps, workspaceId, "variable-sets:use");
-      return c.json(await requireVariableSetForApi(db, workspaceId, c.req.param("variableSetId")));
-    });
-    app.patch(`${prefix}/:variableSetId`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant7(c, deps, workspaceId, "variable-sets:manage");
-      const variableSet = await requireVariableSetForApi(
-        db,
-        workspaceId,
-        c.req.param("variableSetId")
-      );
-      const payload = UpdateVariableSetRequest.parse(await c.req.json());
-      const name = payload.name !== void 0 ? trimmedVariableSetName(payload.name) : void 0;
-      if (name !== void 0 && name !== variableSet.name) {
-        const existing = await getVariableSetByName2(db, workspaceId, name);
-        if (existing && existing.id !== variableSet.id) {
-          throw new HTTPException12(409, { message: `variable set name is already in use: ${name}` });
-        }
-      }
-      const updated = await updateVariableSet(db, workspaceId, variableSet.id, {
-        ...name !== void 0 ? { name } : {},
-        ...payload.description !== void 0 ? { description: payload.description } : {}
-      });
-      await recordVariableSetAuditEvent2(db, {
-        grant,
-        action: "variable_set.updated",
-        variableSetId: variableSet.id
-      });
-      return c.json(updated);
-    });
-    app.delete(`${prefix}/:variableSetId`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant7(c, deps, workspaceId, "variable-sets:manage");
-      const variableSet = await requireVariableSetForApi(
-        db,
-        workspaceId,
-        c.req.param("variableSetId")
-      );
-      const attachedTasks = await countScheduledTasksUsingVariableSet(
-        db,
-        workspaceId,
-        variableSet.id
-      );
-      if (attachedTasks > 0) {
-        throw new HTTPException12(409, {
-          message: `variable set is attached to ${attachedTasks} scheduled task(s); detach first`
-        });
+    }
+  }
+  const startLimiter = new TokenBucket({ capacity: 10, refillPerSecond: 0.5 });
+  const pollLimiter = new TokenBucket({ capacity: 60, refillPerSecond: 2 });
+  const lookupLimiter = new TokenBucket({ capacity: 30, refillPerSecond: 1 });
+  const exchangeLimiter = new TokenBucket({ capacity: 20, refillPerSecond: 0.5 });
+  function rateLimit(c, limiter) {
+    const ip = clientIp(c);
+    if (!limiter.take(ip)) {
+      throw new HTTPException11(429, { message: "too many requests; slow down" });
+    }
+  }
+  app.post("/v1/enrollments/device/start", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, startLimiter);
+    const parsed = DeviceEnrollmentStartRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid device-start request" });
+    }
+    const body = parsed.data;
+    const workspace = await getWorkspace(db, body.workspaceId);
+    if (!workspace) {
+      throw new HTTPException11(404, { message: "workspace not found" });
+    }
+    const result = await startDeviceEnrollment(
+      { db, settings },
+      {
+        accountId: workspace.accountId,
+        workspaceId: workspace.id,
+        publicKey: body.publicKey,
+        os: body.os,
+        arch: body.arch,
+        machineName: body.machineName ?? null,
+        canOfferDisplay: body.canOfferDisplay,
+        requestsScreenControl: body.requestsScreenControl,
+        // The approve page is served at the SAME origin as this request.
+        verificationOrigin: new URL(c.req.url).origin
       }
-      const activeSessions = await countActiveSessionsUsingVariableSet(
-        db,
+    );
+    return c.json(result, 201);
+  });
+  app.post("/v1/enrollments/device/poll", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, pollLimiter);
+    const parsed = DeviceEnrollmentPollRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid device-poll request" });
+    }
+    const result = await pollDeviceEnrollment(
+      { db, settings },
+      { deviceCode: parsed.data.deviceCode }
+    );
+    return c.json(result, 200);
+  });
+  app.post("/v1/enrollments/device/lookup", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, lookupLimiter);
+    const parsed = DeviceEnrollmentLookupRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid device-lookup request" });
+    }
+    const record3 = await lookupDeviceEnrollment(
+      { db, settings },
+      { userCode: parsed.data.userCode }
+    );
+    if (!record3) {
+      throw new HTTPException11(404, { message: "no pending enrollment for that code" });
+    }
+    try {
+      await requireAccessGrant6(c, deps, record3.workspaceId, "enrollments:read");
+    } catch {
+      throw new HTTPException11(404, { message: "no pending enrollment for that code" });
+    }
+    return c.json(DeviceEnrollmentLookupResponse.parse(toLookupResponse(record3)), 200);
+  });
+  app.post("/v1/enrollments/token/exchange", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, exchangeLimiter);
+    const parsed = EnrollTokenExchangeRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid enroll-token-exchange request" });
+    }
+    const body = parsed.data;
+    const result = await exchangeEnrollToken(
+      { db, settings },
+      {
+        token: body.token,
+        publicKey: body.publicKey,
+        os: body.os,
+        arch: body.arch,
+        machineName: body.machineName ?? null,
+        canOfferDisplay: body.canOfferDisplay
+      }
+    );
+    if (!result.ok) {
+      if (result.reason === "disabled") {
+        throw new HTTPException11(503, { message: "enrollment credential plane is not configured" });
+      }
+      throw new HTTPException11(401, { message: "invalid or expired enroll token" });
+    }
+    return c.json(EnrollTokenExchangeResponse.parse({ credentials: result.credentials }), 201);
+  });
+  app.post("/v1/workspaces/:workspaceId/enrollments/device/approve", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant6(c, deps, workspaceId, "enrollments:manage");
+    assertSelfhostedEnabled();
+    const parsed = DeviceEnrollmentApproveRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid device-approve request" });
+    }
+    const body = parsed.data;
+    const approved = await approveDeviceEnrollment(
+      { db, settings },
+      {
+        accountId: grant.accountId,
         workspaceId,
-        variableSet.id
-      );
-      if (activeSessions > 0) {
-        throw new HTTPException12(409, {
-          message: `variable set is attached to ${activeSessions} active session(s); wait for them to finish or cancel them first`
-        });
+        userCode: body.userCode,
+        allowScreenControl: body.allowScreenControl,
+        // The LOUD consent record: WHO consented (the authenticated subject + label).
+        approvedBySubjectId: grant.subjectId,
+        approvedBySubjectLabel: grant.subjectLabel ?? null
       }
-      await deleteVariableSet(db, workspaceId, variableSet.id);
-      await recordVariableSetAuditEvent2(db, {
-        grant,
-        action: "variable_set.deleted",
-        variableSetId: variableSet.id
-      });
-      return c.json({ ok: true });
-    });
-    app.put(`${prefix}/:variableSetId/variables/:name`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant7(c, deps, workspaceId, "variable-sets:manage");
-      const key = requireVariableSetEncryption2(settings);
-      const name = parseVariableName(c.req.param("name"));
-      const variableSet = await requireVariableSetForApi(
-        db,
+    );
+    if (!approved) {
+      throw new HTTPException11(404, { message: "no pending enrollment for that code" });
+    }
+    return c.json(
+      DeviceEnrollmentApproveResponse.parse({
+        approved: true,
+        enrollmentId: approved.enrollmentId,
+        sandboxId: approved.sandboxId,
+        allowScreenControl: approved.allowScreenControl
+      }),
+      201
+    );
+  });
+  app.post("/v1/workspaces/:workspaceId/enrollments/device/deny", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant6(c, deps, workspaceId, "enrollments:manage");
+    assertSelfhostedEnabled();
+    const parsed = DeviceEnrollmentDenyRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid device-deny request" });
+    }
+    const result = await denyDeviceEnrollment(
+      { db, settings },
+      {
+        accountId: grant.accountId,
         workspaceId,
-        c.req.param("variableSetId")
-      );
-      const payload = SetVariableSetVariableRequest.parse(await c.req.json());
-      const exists = variableSet.variables.some((variable) => variable.name === name);
-      if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT2) {
-        throw new HTTPException12(422, {
-          message: `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT2} variables`
-        });
+        userCode: parsed.data.userCode
       }
-      const metadata = await setVariableSetVariable2(db, {
+    );
+    return c.json(DeviceEnrollmentDenyResponse.parse({ denied: result.denied }), 200);
+  });
+  app.post("/v1/workspaces/:workspaceId/enrollments/token", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant6(c, deps, workspaceId, "enrollments:manage");
+    assertSelfhostedEnabled();
+    const parsed = MintEnrollTokenRequest.safeParse(await c.req.json().catch(() => ({})));
+    if (!parsed.success) {
+      throw new HTTPException11(400, { message: "invalid mint-enroll-token request" });
+    }
+    const minted = await mintEnrollToken(
+      { db, settings },
+      {
         accountId: grant.accountId,
         workspaceId,
-        variableSetId: variableSet.id,
-        name,
-        valueEncrypted: encryptVariableSetValue2(key, payload.value)
-      });
-      await recordVariableSetAuditEvent2(db, {
-        grant,
-        action: "variable_set.variable.set",
-        variableSetId: variableSet.id,
-        variableName: name
-      });
-      return c.json(metadata);
+        allowScreenControl: parsed.data.allowScreenControl
+      }
+    );
+    if (!minted) {
+      throw new HTTPException11(503, { message: "enrollment credential plane is not configured" });
+    }
+    return c.json(MintEnrollTokenResponse.parse(minted), 201);
+  });
+  app.get("/v1/workspaces/:workspaceId/enrollments", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant6(c, deps, workspaceId, "enrollments:read");
+    assertSelfhostedEnabled();
+    const statusFilter = c.req.query("status");
+    const rows = await listEnrollments(
+      db,
+      workspaceId,
+      statusFilter === "active" ? { status: "active" } : {}
+    );
+    return c.json(
+      ListEnrollmentsResponse.parse({
+        enrollments: rows.map(
+          (row) => EnrollmentSummary.parse({
+            id: row.id,
+            pubkey: row.pubkey,
+            exposure: row.exposure,
+            hasDisplay: row.hasDisplay,
+            desktopUnavailableReason: row.desktopUnavailableReason,
+            allowScreenControl: row.allowScreenControl,
+            status: row.status,
+            os: row.os,
+            arch: row.arch,
+            lastSeenAt: row.lastSeenAt,
+            createdAt: row.createdAt,
+            revokedAt: row.revokedAt
+          })
+        )
+      })
+    );
+  });
+  app.post("/v1/workspaces/:workspaceId/enrollments/:enrollmentId/revoke", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant6(c, deps, workspaceId, "enrollments:manage");
+    assertSelfhostedEnabled();
+    const result = await revokeEnrollment(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      enrollmentId: c.req.param("enrollmentId")
     });
-    app.delete(`${prefix}/:variableSetId/variables/:name`, async (c) => {
-      const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant7(c, deps, workspaceId, "variable-sets:manage");
-      const name = parseVariableName(c.req.param("name"));
-      const variableSet = await requireVariableSetForApi(
-        db,
-        workspaceId,
-        c.req.param("variableSetId")
-      );
-      const deleted = await deleteVariableSetVariable(db, workspaceId, variableSet.id, name);
-      if (!deleted) {
-        throw new HTTPException12(404, { message: "variable set variable not found" });
+    return c.json(RevokeEnrollmentResponse.parse(result));
+  });
+}
+function clientIp(c) {
+  const xff = c.req.header("x-forwarded-for");
+  if (xff) {
+    const first = xff.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  return c.req.header("x-real-ip")?.trim() || "unknown";
+}
+var TokenBucket = class {
+  capacity;
+  refillPerSecond;
+  buckets = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.capacity = options.capacity;
+    this.refillPerSecond = options.refillPerSecond;
+  }
+  take(key, now = Date.now()) {
+    const bucket = this.buckets.get(key) ?? { tokens: this.capacity, updatedAt: now };
+    const elapsedSeconds = Math.max(0, (now - bucket.updatedAt) / 1e3);
+    bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsedSeconds * this.refillPerSecond);
+    bucket.updatedAt = now;
+    if (bucket.tokens >= this.capacity && this.buckets.size > 1e4) {
+      this.buckets.delete(key);
+    }
+    if (bucket.tokens < 1) {
+      this.buckets.set(key, bucket);
+      return false;
+    }
+    bucket.tokens -= 1;
+    this.buckets.set(key, bucket);
+    return true;
+  }
+};
+
+// src/routes/machines.ts
+import {
+  MachineMetricsSeriesResponse,
+  MachinesResponse,
+  SwapActiveSandboxRequest,
+  SwapActiveSandboxResponse
+} from "@opengeni/contracts";
+import { getEnrollment as getEnrollment2, readMachineMetricsSeries, requireSession as requireSession3 } from "@opengeni/db";
+import { HTTPException as HTTPException12 } from "hono/http-exception";
+import { requireAccessGrant as requireAccessGrant7 } from "@opengeni/core";
+import { buildFleetContextForSession as buildFleetContextForSession2, swapActiveSandbox as swapActiveSandbox2 } from "@opengeni/core";
+
+// src/sandbox/machines.ts
+import {
+  getSession as getSession3,
+  listEnrollments as listEnrollments2,
+  listSandboxes,
+  readActiveSandbox,
+  readLease as readLease2,
+  readMachineMetricsLatestForWorkspace
+} from "@opengeni/db";
+import { MachineView, MetricSample } from "@opengeni/contracts";
+import {
+  NatsControlRpc as NatsControlRpc2,
+  selfhostedLiveness,
+  SelfhostedSession
+} from "@opengeni/runtime/sandbox";
+import { relayConfigFromSettings as relayConfigFromSettings2 } from "@opengeni/core";
+var PROBE_TIMEOUT_MS = 5e3;
+function controlRpc2(bus) {
+  return new NatsControlRpc2(async () => {
+    if (!bus) {
+      return null;
+    }
+    return bus.getRequestConnection();
+  });
+}
+function metricRowToSample(row) {
+  return MetricSample.parse({
+    cpuPct: row.cpuPercent ?? 0,
+    load1: row.load1 ?? 0,
+    load5: row.load5 ?? 0,
+    load15: row.load15 ?? 0,
+    memUsedBytes: row.memUsedBytes ?? 0,
+    memTotalBytes: row.memTotalBytes ?? 0,
+    diskUsedBytes: row.diskUsedBytes ?? 0,
+    diskTotalBytes: row.diskTotalBytes ?? 0,
+    gpuUtilPct: row.gpuUtilPercent,
+    gpuMemBytes: row.gpuMemUsedBytes,
+    runQueue: row.contention ?? 0,
+    sampledAt: row.sampledAt
+  });
+}
+async function probeEnrollment(services, workspaceId, enrollment) {
+  const { settings, bus } = services;
+  let probeResponded = false;
+  if (enrollment.status === "active") {
+    const session = new SelfhostedSession({
+      workspaceId,
+      agentId: enrollment.id,
+      controlRpc: controlRpc2(bus),
+      relay: relayConfigFromSettings2(settings),
+      timeoutMs: PROBE_TIMEOUT_MS
+    });
+    try {
+      probeResponded = await session.ping();
+    } catch {
+      probeResponded = false;
+    }
+  }
+  const derived = selfhostedLiveness({
+    enrollment: {
+      status: enrollment.status,
+      exposure: enrollment.exposure,
+      allowScreenControl: enrollment.allowScreenControl,
+      hasDisplay: enrollment.hasDisplay,
+      lastSeenAt: enrollment.lastSeenAt,
+      wentOfflineAt: enrollment.wentOfflineAt,
+      wentOfflineReason: enrollment.wentOfflineReason
+    },
+    probeResponded
+  });
+  return { state: derived.state, consented: derived.consented, hasDisplay: derived.hasDisplay };
+}
+function machineStateFor(liveness, hasDisplay) {
+  if (liveness !== "online") {
+    return liveness;
+  }
+  if (!hasDisplay) {
+    return "display_unavailable";
+  }
+  return "online";
+}
+async function listMachines(services, input) {
+  const { db } = services;
+  const { workspaceId } = input;
+  let activeSandboxId = null;
+  let activeEpoch = 0;
+  let session = null;
+  if (input.sessionId) {
+    session = await getSession3(db, workspaceId, input.sessionId);
+    if (session) {
+      const pointer = await readActiveSandbox(db, workspaceId, input.sessionId);
+      activeSandboxId = pointer?.activeSandboxId ?? null;
+      activeEpoch = pointer?.activeEpoch ?? 0;
+    }
+  }
+  const machines = [];
+  if (session) {
+    const groupActive = activeSandboxId === null;
+    const groupLease = await readLease2(db, workspaceId, session.sandboxGroupId);
+    machines.push(
+      MachineView.parse({
+        sandboxId: session.sandboxGroupId,
+        enrollmentId: null,
+        name: "session sandbox",
+        kind: session.sandboxBackend === "selfhosted" ? "selfhosted" : "modal",
+        state: "online",
+        active: groupActive,
+        isSessionGroup: true,
+        workspaceGeneration: groupLease?.workspaceGeneration ?? null,
+        archiveGeneration: groupLease?.archiveGeneration ?? null,
+        archiveComplete: groupLease?.archiveComplete ?? false,
+        // The Modal group box is a cloud Linux box; its precise OS/arch is not
+        // surfaced as a metric, so the dashboard shows the canonical linux/x86_64.
+        os: "linux",
+        arch: "x86_64",
+        hasDisplay: false,
+        desktopUnavailableReason: null,
+        allowScreenControl: false,
+        sharedSessionCount: 1,
+        lastSeenAt: null,
+        metrics: null
+      })
+    );
+  }
+  const [sandboxes, enrollments, metricsByEnrollment] = await Promise.all([
+    listSandboxes(db, workspaceId),
+    listEnrollments2(db, workspaceId),
+    readMachineMetricsLatestForWorkspace(db, workspaceId)
+  ]);
+  const enrollmentById = new Map(enrollments.map((e) => [e.id, e]));
+  const machineViews = await Promise.all(
+    sandboxes.map(async (sandbox) => {
+      if (sandbox.kind !== "selfhosted" || !sandbox.enrollmentId) {
+        return null;
       }
-      await recordVariableSetAuditEvent2(db, {
-        grant,
-        action: "variable_set.variable.deleted",
-        variableSetId: variableSet.id,
-        variableName: name
+      const enrollment = enrollmentById.get(sandbox.enrollmentId) ?? null;
+      if (!enrollment) {
+        return null;
+      }
+      const [probe, lease] = await Promise.all([
+        probeEnrollment(services, workspaceId, enrollment),
+        readLease2(db, workspaceId, sandbox.id)
+      ]);
+      const state = machineStateFor(probe.state, probe.hasDisplay);
+      const sharedSessionCount = lease?.refcount ?? 0;
+      const metricsRow = metricsByEnrollment.get(enrollment.id) ?? null;
+      return MachineView.parse({
+        sandboxId: sandbox.id,
+        enrollmentId: enrollment.id,
+        name: sandbox.name,
+        kind: "selfhosted",
+        state,
+        active: activeSandboxId === sandbox.id,
+        isSessionGroup: false,
+        workspaceGeneration: null,
+        archiveGeneration: null,
+        archiveComplete: false,
+        os: enrollment.os,
+        arch: enrollment.arch,
+        hasDisplay: enrollment.hasDisplay,
+        desktopUnavailableReason: enrollment.desktopUnavailableReason,
+        allowScreenControl: enrollment.allowScreenControl,
+        sharedSessionCount,
+        lastSeenAt: enrollment.lastSeenAt,
+        metrics: metricsRow ? metricRowToSample(metricsRow) : null
       });
-      return c.json({ ok: true });
-    });
-  }
-}
-var registerEnvironmentRoutes = registerVariableSetRoutes;
-function parseVariableName(raw) {
-  const parsed = VariableSetVariableName2.safeParse(raw);
-  if (!parsed.success) {
-    throw new HTTPException12(422, {
-      message: "variable set variable names must match ^[A-Z][A-Z0-9_]*$"
-    });
-  }
-  assertAllowedVariableSetVariableName2(parsed.data);
-  return parsed.data;
-}
-function trimmedVariableSetName(name) {
-  const trimmed = name.trim();
-  if (!trimmed) {
-    throw new HTTPException12(422, { message: "variable set name is required" });
-  }
-  return trimmed;
+    })
+  );
+  machines.push(...machineViews.filter((machine) => machine !== null));
+  return { activeSandboxId, activeEpoch, machines };
 }
 
-// src/routes/files.ts
-import {
-  CompleteFileUploadResponse,
-  CreateFileUploadRequest,
-  CreateFileUploadResponse,
-  FileAsset,
-  FileDownloadUrlResponse,
-  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
-  RETAINED_OUTPUT_MAX_PAGE_BYTES,
-  RetainedArtifactMetadataSchema,
-  retainedArtifactReferenceFromFile,
-  resolveRetainedOutputRange
-} from "@opengeni/contracts";
-import {
-  claimFileUploadCleanup,
-  completeFileUploadCleanup,
-  completeFileUpload,
-  createFileUpload,
-  getFileUpload,
-  getRetainedFileArtifact,
-  requireFile as requireFile2
-} from "@opengeni/db";
-import { HTTPException as HTTPException13 } from "hono/http-exception";
-import { requireAccessGrant as requireAccessGrant8 } from "@opengeni/core";
-import { recordWorkspaceUsage as recordWorkspaceUsage3, requireLimit as requireLimit3 } from "@opengeni/core";
-function registerFileRoutes(app, deps) {
-  const { db, objectStorage } = deps;
-  app.post("/v1/workspaces/:workspaceId/files/uploads", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant8(c, deps, workspaceId, "files:upload");
-    if (!objectStorage) {
-      throw new HTTPException13(503, { message: "object storage is not configured" });
-    }
-    const payload = CreateFileUploadRequest.parse(await c.req.json());
-    await requireLimit3(deps, {
-      accountId: grant.accountId,
-      workspaceId,
-      action: "file:upload",
-      quantity: payload.sizeBytes
-    });
-    if (payload.sizeBytes > objectStorage.maxSinglePutSizeBytes) {
-      throw new HTTPException13(413, {
-        message: `file exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes`
+// src/routes/machines.ts
+var SERIES_WINDOWS_MS = {
+  "15m": 15 * 6e4,
+  "1h": 60 * 6e4,
+  "6h": 6 * 60 * 6e4,
+  "24h": 24 * 60 * 6e4
+};
+var DEFAULT_SERIES_WINDOW_MS = SERIES_WINDOWS_MS["1h"];
+function registerMachineRoutes(app, deps) {
+  const { settings, db, bus } = deps;
+  function assertSelfhostedEnabled() {
+    if (!settings.sandboxSelfhostedEnabled) {
+      throw new HTTPException12(404, {
+        message: "selfhosted machines are not enabled for this deployment"
       });
     }
-    const fileId = crypto.randomUUID();
-    const safeFilename = sanitizeFilename(payload.filename);
-    const objectKey = `workspaces/${workspaceId}/files/${fileId}/original/${safeFilename}`;
-    const signed = await objectStorage.createPutUrl({
-      key: objectKey,
-      contentType: payload.contentType,
-      ...payload.sha256 ? { sha256: payload.sha256 } : {}
-    });
-    const upload = await createFileUpload(db, {
+  }
+  app.get("/v1/workspaces/:workspaceId/machines", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant7(c, deps, workspaceId, "enrollments:read");
+    assertSelfhostedEnabled();
+    const sessionId = c.req.query("sessionId") ?? null;
+    const response = await listMachines({ db, settings, bus }, { workspaceId, sessionId });
+    return c.json(MachinesResponse.parse(response));
+  });
+  app.get("/v1/workspaces/:workspaceId/machines/:enrollmentId/metrics/series", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant7(c, deps, workspaceId, "enrollments:read");
+    assertSelfhostedEnabled();
+    const enrollmentId = c.req.param("enrollmentId");
+    const enrollment = await getEnrollment2(db, workspaceId, enrollmentId);
+    if (!enrollment) {
+      throw new HTTPException12(404, { message: "machine not found in this workspace" });
+    }
+    const windowMs = SERIES_WINDOWS_MS[c.req.query("window") ?? ""] ?? DEFAULT_SERIES_WINDOW_MS;
+    const since = new Date(Date.now() - windowMs);
+    const rows = await readMachineMetricsSeries(db, { workspaceId, enrollmentId, since });
+    return c.json(
+      MachineMetricsSeriesResponse.parse({
+        samples: rows.map(metricRowToSample)
+      })
+    );
+  });
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/active-sandbox", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant7(c, deps, workspaceId, "sessions:control");
+    assertSelfhostedEnabled();
+    const sessionId = c.req.param("sessionId");
+    const body = SwapActiveSandboxRequest.parse(await c.req.json());
+    const ctx = await buildFleetContextForSession2(deps, {
       accountId: grant.accountId,
       workspaceId,
-      fileId,
-      filename: payload.filename,
-      safeFilename,
-      contentType: payload.contentType,
-      sizeBytes: payload.sizeBytes,
-      sha256: payload.sha256 ?? null,
-      bucket: objectStorage.bucket,
-      objectKey,
-      expiresAt: signed.expiresAt
+      sessionId
     });
-    return c.json(
-      CreateFileUploadResponse.parse({
-        fileId: upload.file.id,
-        uploadId: upload.uploadId,
-        putUrl: signed.url,
-        requiredHeaders: signed.requiredHeaders,
-        expiresAt: upload.expiresAt,
-        maxSizeBytes: objectStorage.maxSinglePutSizeBytes
-      }),
-      201
+    const result = await swapActiveSandbox2(
+      {
+        db,
+        settings,
+        bus,
+        ensureSessionGroupReady: async (fleetCtx) => {
+          const session = await requireSession3(db, fleetCtx.workspaceId, fleetCtx.sessionId);
+          return await ensureSessionGroupReady(
+            { db, settings, bus },
+            {
+              accountId: fleetCtx.accountId,
+              workspaceId: fleetCtx.workspaceId,
+              session
+            }
+          );
+        }
+      },
+      ctx,
+      body.target
     );
+    return c.json(SwapActiveSandboxResponse.parse(result));
   });
-  app.post("/v1/workspaces/:workspaceId/files/uploads/:uploadId/complete", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant8(c, deps, workspaceId, "files:upload");
-    if (!objectStorage) {
-      throw new HTTPException13(503, { message: "object storage is not configured" });
-    }
-    const upload = await getFileUpload(db, workspaceId, c.req.param("uploadId"));
-    if (!upload) {
-      throw new HTTPException13(404, { message: "file upload not found" });
-    }
-    const recordUploadedFileUsage = async (file2) => {
-      await recordWorkspaceUsage3(deps, {
-        accountId: grant.accountId,
-        workspaceId,
-        subjectId: grant.subjectId,
-        eventType: "file.uploaded",
-        quantity: file2.sizeBytes,
-        unit: "byte",
-        sourceResourceType: "file",
-        sourceResourceId: file2.id,
-        idempotencyKey: `file.uploaded:${workspaceId}:${file2.id}`
-      });
-    };
-    const completeAndRecordUsage = async () => {
-      let file2;
-      try {
-        file2 = await completeFileUpload(db, workspaceId, upload.id);
-      } catch (error) {
-        const current = await getFileUpload(db, workspaceId, upload.id);
-        if (current?.status === "completed" && current.file.status === "ready") {
-          file2 = current.file;
-        } else if (current && current.status !== "pending") {
-          throw new HTTPException13(409, {
-            message: `file upload is ${publicFileUploadStatus(current.status)}`
+}
+
+// src/routes/environments.ts
+import {
+  CreateVariableSetRequest,
+  SetVariableSetVariableRequest,
+  UpdateVariableSetRequest,
+  VariableSetVariableName as VariableSetVariableName2
+} from "@opengeni/contracts";
+import {
+  countActiveSessionsUsingVariableSet,
+  countScheduledTasksUsingVariableSet,
+  countVariableSets as countVariableSets2,
+  createVariableSet as createVariableSet2,
+  deleteVariableSet,
+  deleteVariableSetVariable,
+  encryptVariableSetValue as encryptVariableSetValue2,
+  getVariableSetByName as getVariableSetByName2,
+  listVariableSets as listVariableSets2,
+  setVariableSetVariable as setVariableSetVariable2,
+  updateVariableSet
+} from "@opengeni/db";
+import { HTTPException as HTTPException13 } from "hono/http-exception";
+import { requireAccessGrant as requireAccessGrant8 } from "@opengeni/core";
+import {
+  assertAllowedVariableSetVariableName as assertAllowedVariableSetVariableName2,
+  MAX_ENVIRONMENTS_PER_WORKSPACE as MAX_ENVIRONMENTS_PER_WORKSPACE2,
+  MAX_VARIABLES_PER_ENVIRONMENT as MAX_VARIABLES_PER_ENVIRONMENT2,
+  recordVariableSetAuditEvent as recordVariableSetAuditEvent2,
+  requireVariableSetEncryption as requireVariableSetEncryption2,
+  requireVariableSetForApi
+} from "@opengeni/core";
+function registerVariableSetRoutes(app, deps) {
+  const { settings, db } = deps;
+  const prefixes = [
+    "/v1/workspaces/:workspaceId/variable-sets",
+    "/v1/workspaces/:workspaceId/environments"
+  ];
+  for (const prefix of prefixes) {
+    app.get(`${prefix}`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      await requireAccessGrant8(c, deps, workspaceId, "variable-sets:use");
+      return c.json(await listVariableSets2(db, workspaceId));
+    });
+    app.post(`${prefix}`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant8(c, deps, workspaceId, "variable-sets:manage");
+      const key = requireVariableSetEncryption2(settings);
+      const payload = CreateVariableSetRequest.parse(await c.req.json());
+      const name = trimmedVariableSetName(payload.name);
+      if (payload.variables.length > MAX_VARIABLES_PER_ENVIRONMENT2) {
+        throw new HTTPException13(422, {
+          message: `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT2} variables`
+        });
+      }
+      const variableNames = /* @__PURE__ */ new Set();
+      for (const variable of payload.variables) {
+        assertAllowedVariableSetVariableName2(variable.name);
+        if (variableNames.has(variable.name)) {
+          throw new HTTPException13(422, {
+            message: `duplicate variable set variable name: ${variable.name}`
           });
-        } else {
-          throw error;
         }
+        variableNames.add(variable.name);
       }
-      await recordUploadedFileUsage(file2);
-      return file2;
-    };
-    const rejectAndCleanObject = async (status, message, terminalStatus) => {
-      const claim = await claimFileUploadCleanup(db, {
-        workspaceId,
-        uploadId: upload.id,
-        fileId: upload.file.id
-      });
-      if (claim.outcome === "completed") {
-        await recordUploadedFileUsage(claim.file);
-        return claim.file;
-      }
-      if (claim.outcome === "unavailable") {
-        throw new HTTPException13(409, {
-          message: `file upload is ${publicFileUploadStatus(claim.status)}`
+      if (await countVariableSets2(db, workspaceId) >= MAX_ENVIRONMENTS_PER_WORKSPACE2) {
+        throw new HTTPException13(422, {
+          message: `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE2} variable sets`
         });
       }
-      try {
-        await objectStorage.deleteObject(upload.file.objectKey);
-      } catch (error) {
-        deps.observability?.warn(
-          "file upload rejection cleanup failed; claim remains reclaimable",
-          {
-            workspaceId,
-            fileId: upload.file.id,
-            uploadId: upload.id,
-            error: error instanceof Error ? error.message : String(error)
-          }
-        );
-        throw new HTTPException13(status, { message });
+      if (await getVariableSetByName2(db, workspaceId, name)) {
+        throw new HTTPException13(409, { message: `variable set name is already in use: ${name}` });
       }
-      const settled = await completeFileUploadCleanup(db, {
+      const created = await createVariableSet2(db, {
         accountId: grant.accountId,
         workspaceId,
-        uploadId: upload.id,
-        fileId: upload.file.id,
-        terminalStatus
+        name,
+        description: payload.description ?? null,
+        variables: payload.variables.map((variable) => ({
+          name: variable.name,
+          valueEncrypted: encryptVariableSetValue2(key, variable.value)
+        }))
       });
-      if (!settled) {
-        throw new HTTPException13(409, { message: "file upload cleanup claim was superseded" });
+      await recordVariableSetAuditEvent2(db, {
+        grant,
+        action: "variable_set.created",
+        variableSetId: created.id
+      });
+      return c.json(created, 201);
+    });
+    app.get(`${prefix}/:variableSetId`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      await requireAccessGrant8(c, deps, workspaceId, "variable-sets:use");
+      return c.json(await requireVariableSetForApi(db, workspaceId, c.req.param("variableSetId")));
+    });
+    app.patch(`${prefix}/:variableSetId`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant8(c, deps, workspaceId, "variable-sets:manage");
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")
+      );
+      const payload = UpdateVariableSetRequest.parse(await c.req.json());
+      const name = payload.name !== void 0 ? trimmedVariableSetName(payload.name) : void 0;
+      if (name !== void 0 && name !== variableSet.name) {
+        const existing = await getVariableSetByName2(db, workspaceId, name);
+        if (existing && existing.id !== variableSet.id) {
+          throw new HTTPException13(409, { message: `variable set name is already in use: ${name}` });
+        }
       }
-      throw new HTTPException13(status, { message });
-    };
-    if (upload.status === "completed" && upload.file.status === "ready") {
-      const file2 = await completeAndRecordUsage();
-      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
-    }
-    if (upload.status !== "pending") {
-      throw new HTTPException13(409, {
-        message: `file upload is ${publicFileUploadStatus(upload.status)}`
+      const updated = await updateVariableSet(db, workspaceId, variableSet.id, {
+        ...name !== void 0 ? { name } : {},
+        ...payload.description !== void 0 ? { description: payload.description } : {}
       });
-    }
-    if (upload.expiresAt.getTime() < Date.now()) {
-      const file2 = await rejectAndCleanObject(409, "file upload has expired", "expired");
-      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
-    }
-    const head = await objectStorage.headFile(upload.file).catch((error) => {
-      throw new HTTPException13(409, {
-        message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}`
+      await recordVariableSetAuditEvent2(db, {
+        grant,
+        action: "variable_set.updated",
+        variableSetId: variableSet.id
       });
+      return c.json(updated);
     });
-    if (Number(head.ContentLength ?? -1) !== upload.file.sizeBytes) {
-      const file2 = await rejectAndCleanObject(
-        422,
-        "uploaded object size does not match file metadata",
-        "failed"
+    app.delete(`${prefix}/:variableSetId`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant8(c, deps, workspaceId, "variable-sets:manage");
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")
       );
-      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
-    }
-    if (upload.file.contentType && head.ContentType && head.ContentType !== upload.file.contentType) {
-      const file2 = await rejectAndCleanObject(
-        422,
-        "uploaded object content type does not match file metadata",
-        "failed"
+      const attachedTasks = await countScheduledTasksUsingVariableSet(
+        db,
+        workspaceId,
+        variableSet.id
       );
-      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
-    }
-    if (upload.file.sha256 && head.Metadata?.sha256 !== upload.file.sha256) {
-      const file2 = await rejectAndCleanObject(
-        422,
-        "uploaded object checksum metadata does not match file metadata",
-        "failed"
+      if (attachedTasks > 0) {
+        throw new HTTPException13(409, {
+          message: `variable set is attached to ${attachedTasks} scheduled task(s); detach first`
+        });
+      }
+      const activeSessions = await countActiveSessionsUsingVariableSet(
+        db,
+        workspaceId,
+        variableSet.id
       );
-      return c.json(CompleteFileUploadResponse.parse({ file: file2 }));
-    }
-    const file = await completeAndRecordUsage();
-    return c.json(CompleteFileUploadResponse.parse({ file }));
-  });
-  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant8(c, deps, workspaceId, "files:read");
-    const file = await requireFile2(db, workspaceId, c.req.param("fileId")).catch(() => null);
-    if (!file) {
-      throw new HTTPException13(404, { message: "file not found" });
-    }
-    return c.json(FileAsset.parse(file));
-  });
-  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant8(c, deps, workspaceId, "files:read");
-    const artifactId = retainedArtifactId(c.req.param("artifactId"));
-    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
-    if (!artifact) {
-      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
-    }
-    return c.json(retainedArtifactMetadata(artifact));
-  });
-  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId/content", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant8(c, deps, workspaceId, "files:read");
-    const artifactId = retainedArtifactId(c.req.param("artifactId"));
-    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
-    if (!artifact) {
-      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
-    }
-    const metadata = retainedArtifactMetadata(artifact);
-    if (!metadata.available) {
-      return c.json(metadata, retainedArtifactUnavailableStatus(metadata.reason));
-    }
-    if (!objectStorage) {
-      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 503);
-    }
-    const rangeHeader = c.req.header("range");
-    const range = resolveRetainedOutputRange(
-      rangeHeader,
-      metadata.originalBytes,
-      rangeHeader ? RETAINED_OUTPUT_MAX_PAGE_BYTES : RETAINED_OUTPUT_DEFAULT_PAGE_BYTES
-    );
-    if (range.kind === "invalid") {
-      return c.json(
-        {
-          message: "invalid retained artifact byte range",
-          reason: range.reason,
-          maxRangeBytes: RETAINED_OUTPUT_MAX_PAGE_BYTES
-        },
-        400
+      if (activeSessions > 0) {
+        throw new HTTPException13(409, {
+          message: `variable set is attached to ${activeSessions} active session(s); wait for them to finish or cancel them first`
+        });
+      }
+      await deleteVariableSet(db, workspaceId, variableSet.id);
+      await recordVariableSetAuditEvent2(db, {
+        grant,
+        action: "variable_set.deleted",
+        variableSetId: variableSet.id
+      });
+      return c.json({ ok: true });
+    });
+    app.put(`${prefix}/:variableSetId/variables/:name`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant8(c, deps, workspaceId, "variable-sets:manage");
+      const key = requireVariableSetEncryption2(settings);
+      const name = parseVariableName(c.req.param("name"));
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")
       );
-    }
-    if (range.kind === "unsatisfiable") {
-      return c.json(
-        { message: "retained artifact byte range is not satisfiable", reason: range.reason },
-        416,
-        {
-          "Accept-Ranges": "bytes",
-          "Content-Range": range.contentRange,
-          "Cache-Control": "private, no-store"
-        }
+      const payload = SetVariableSetVariableRequest.parse(await c.req.json());
+      const exists = variableSet.variables.some((variable) => variable.name === name);
+      if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT2) {
+        throw new HTTPException13(422, {
+          message: `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT2} variables`
+        });
+      }
+      const metadata = await setVariableSetVariable2(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        variableSetId: variableSet.id,
+        name,
+        valueEncrypted: encryptVariableSetValue2(key, payload.value)
+      });
+      await recordVariableSetAuditEvent2(db, {
+        grant,
+        action: "variable_set.variable.set",
+        variableSetId: variableSet.id,
+        variableName: name
+      });
+      return c.json(metadata);
+    });
+    app.delete(`${prefix}/:variableSetId/variables/:name`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant8(c, deps, workspaceId, "variable-sets:manage");
+      const name = parseVariableName(c.req.param("name"));
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")
       );
-    }
-    const headers = {
-      "Accept-Ranges": range.acceptRanges,
-      "Cache-Control": "private, no-store",
-      "Content-Length": String(range.length),
-      "Content-Type": metadata.contentType,
-      "X-Content-Type-Options": "nosniff",
-      ...range.contentRange ? { "Content-Range": range.contentRange } : {}
-    };
-    if (range.kind === "empty") {
-      if (!await objectStorage.fileExists(artifact.file)) {
-        return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+      const deleted = await deleteVariableSetVariable(db, workspaceId, variableSet.id, name);
+      if (!deleted) {
+        throw new HTTPException13(404, { message: "variable set variable not found" });
       }
-      return c.body(null, 200, headers);
-    }
-    const bytes = await objectStorage.getFileRange(artifact.file, {
-      start: range.start,
-      end: range.end
+      await recordVariableSetAuditEvent2(db, {
+        grant,
+        action: "variable_set.variable.deleted",
+        variableSetId: variableSet.id,
+        variableName: name
+      });
+      return c.json({ ok: true });
     });
-    if (!bytes) {
-      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
-    }
-    if (bytes.byteLength !== range.length) {
-      throw new HTTPException13(502, { message: "object storage returned an invalid byte range" });
-    }
-    return c.body(new Uint8Array(bytes), range.status, headers);
-  });
-  app.post("/v1/workspaces/:workspaceId/files/:fileId/download-url", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant8(c, deps, workspaceId, "files:read");
-    if (!objectStorage) {
-      throw new HTTPException13(503, { message: "object storage is not configured" });
-    }
-    const file = await requireFile2(db, workspaceId, c.req.param("fileId")).catch(() => null);
-    if (!file) {
-      throw new HTTPException13(404, { message: "file not found" });
-    }
-    if (file.status !== "ready") {
-      throw new HTTPException13(409, { message: `file is ${file.status}` });
-    }
-    const signed = await objectStorage.createGetUrl({ key: file.objectKey });
-    return c.json(
-      FileDownloadUrlResponse.parse({
-        url: signed.url,
-        expiresAt: signed.expiresAt.toISOString()
-      })
-    );
-  });
-}
-function sanitizeFilename(filename) {
-  const trimmed = filename.trim().replace(/[/\\]/g, "_");
-  const safe = trimmed.replace(/[^A-Za-z0-9._ -]+/g, "_").replace(/\s+/g, " ").trim();
-  return safe || "file";
-}
-function publicFileUploadStatus(status) {
-  return status === "cleanup_pending" ? "failed" : status;
+  }
 }
-function retainedArtifactId(value) {
-  const parsed = FileAsset.shape.id.safeParse(value);
+var registerEnvironmentRoutes = registerVariableSetRoutes;
+function parseVariableName(raw) {
+  const parsed = VariableSetVariableName2.safeParse(raw);
   if (!parsed.success) {
-    throw new HTTPException13(404, { message: "artifact not found" });
+    throw new HTTPException13(422, {
+      message: "variable set variable names must match ^[A-Z][A-Z0-9_]*$"
+    });
   }
+  assertAllowedVariableSetVariableName2(parsed.data);
   return parsed.data;
 }
-function retainedArtifactUnavailable(artifactId, reason) {
-  return RetainedArtifactMetadataSchema.parse({ available: false, artifactId, reason });
-}
-function retainedArtifactMetadata(artifact) {
-  const reference = retainedArtifactReferenceFromFile(artifact.file);
-  if (reference) return reference;
-  const { file, uploadStatus, uploadExpiresAt } = artifact;
-  if (file.status === "deleted") {
-    return retainedArtifactUnavailable(file.id, "deleted");
-  }
-  if (file.status === "expired" || uploadStatus === "expired" || uploadStatus === "pending" && uploadExpiresAt !== null && uploadExpiresAt.getTime() < Date.now()) {
-    return retainedArtifactUnavailable(file.id, "expired");
-  }
-  if (file.status === "failed" || uploadStatus === "failed" || uploadStatus === "cleanup_pending") {
-    return retainedArtifactUnavailable(file.id, "failed");
-  }
-  if (file.status === "pending_upload" || uploadStatus === "pending") {
-    return retainedArtifactUnavailable(file.id, "pending");
-  }
-  return retainedArtifactUnavailable(file.id, "unsupported");
-}
-function retainedArtifactUnavailableStatus(reason) {
-  switch (reason) {
-    case "deleted":
-      return 404;
-    case "expired":
-    case "missing_storage":
-      return 410;
-    case "unsupported":
-    case "not_retained":
-    case "storage_write_failed":
-      return 422;
-    case "pending":
-    case "failed":
-      return 409;
+function trimmedVariableSetName(name) {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new HTTPException13(422, { message: "variable set name is required" });
   }
+  return trimmed;
 }
 
 // src/routes/api-keys.ts
@@ -10117,27 +10420,37 @@ function looksLikeEmail(value) {
 }
 
 // src/routes/github.ts
-import { GitHubAppManifestCreate } from "@opengeni/contracts";
-import { deleteGitHubInstallationBinding } from "@opengeni/db";
 import {
+  GitHubAppManifestCreate
+} from "@opengeni/contracts";
+import {
+  bindAuthorizedGitHubInstallationRepositories,
+  deleteGitHubInstallationBinding,
+  GitHubInstallationAuthorityCommitError
+} from "@opengeni/db";
+import {
+  authorizeGitHubInstallationBinding,
   buildGitHubAppManifest,
   convertGitHubAppManifest,
-  createSignedState as createSignedState3,
+  createSignedState as createSignedState4,
   envLinesFromGitHubManifestConversion,
   GitHubAppApiError,
   GitHubAppConfigurationError as GitHubAppConfigurationError2,
+  GitHubInstallationAuthorityError,
   githubAppMissingSettings as githubAppMissingSettings2,
+  githubOAuthAuthorizeUrl,
   organizationAppManifestUrl,
   personalAppManifestUrl,
   readSignedState as readSignedState3,
   stateMaxAgeSeconds,
   verifySignedState
 } from "@opengeni/github";
-import { setCookie } from "hono/cookie";
+import { deleteCookie, setCookie } from "hono/cookie";
 import { HTTPException as HTTPException16 } from "hono/http-exception";
-import { requireAccessGrant as requireAccessGrant10 } from "@opengeni/core";
+import { hasPermission as hasPermission5, requireAccessGrant as requireAccessGrant10 } from "@opengeni/core";
 var githubStateCookie = "opengeni_github_state";
-var installationBindingDisabledMessage = "Connecting a GitHub App installation is disabled until GitHub installation authority can be proven";
+var githubBindingStateMaxAgeSeconds = 10 * 60;
+var legacyInstallationChooserDisabledMessage = "The legacy repository-admin GitHub installation chooser is disabled; use the GitHub owner-consent connect flow";
 function registerGitHubRoutes(app, deps) {
   const { db, settings, githubStateSecret } = deps;
   app.get("/v1/workspaces/:workspaceId/github/app", async (c) => {
@@ -10145,17 +10458,25 @@ function registerGitHubRoutes(app, deps) {
     const grant = await requireAccessGrant10(c, deps, workspaceId, "github:use");
     const missing = githubAppMissingSettings2(settings);
     const slug = settings.githubAppSlug?.trim() || null;
+    const installations = missing.length === 0 ? await listWorkspaceGitHubInstallationBindings(deps, grant.workspaceId) : [];
+    const status = githubBindingStatus(missing.length === 0, installations);
+    const canManage = hasPermission5(grant.permissions, "github:manage");
+    const connectState = missing.length === 0 && slug && canManage ? createSignedState4(githubStateSecret, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      intent: "installation_authority",
+      ...githubBrowserGrantClaims(settings, grant)
+    }) : null;
+    const connectUrl = connectState ? `${openGeniBaseUrl(settings, c)}/v1/workspaces/${grant.workspaceId}/github/connect?state=${encodeURIComponent(connectState)}` : null;
     return c.json({
       configured: missing.length === 0,
+      status,
       appId: settings.githubAppId ?? null,
       clientId: settings.githubClientId ?? null,
       appSlug: slug,
-      // Kept nullable for SDK compatibility. GitHub's setup callback contains
-      // a spoofable installation_id, while user-installation visibility and
-      // repository admin permission do not prove that this human may bind it.
-      installUrl: null,
-      linkUrl: null,
-      installations: await listWorkspaceGitHubInstallationBindings(deps, grant.workspaceId),
+      installUrl: connectUrl,
+      linkUrl: connectUrl,
+      installations,
       missing
     });
   });
@@ -10166,10 +10487,22 @@ function registerGitHubRoutes(app, deps) {
       throw new HTTPException16(400, { message: "missing GitHub installation state" });
     }
     const statePayload = readSignedState3(state, githubStateSecret);
-    if (!statePayload || statePayload.workspaceId !== workspaceId) {
+    if (!statePayload || statePayload.intent !== "installation_authority" || statePayload.workspaceId !== workspaceId || typeof statePayload.accountId !== "string" || !isFreshGitHubBindingState(statePayload)) {
       throw new HTTPException16(400, { message: "invalid or expired GitHub installation state" });
     }
-    throw installationBindingDisabled();
+    const slug = settings.githubAppSlug?.trim();
+    if (!slug || githubAppMissingSettings2(settings).length > 0) {
+      throw new HTTPException16(409, {
+        message: JSON.stringify({
+          message: "GitHub App is not configured",
+          missing: githubAppMissingSettings2(settings)
+        })
+      });
+    }
+    setGitHubStateCookie(c, deps, state);
+    return c.redirect(
+      `https://github.com/apps/${slug}/installations/new?state=${encodeURIComponent(state)}`
+    );
   });
   app.get("/v1/workspaces/:workspaceId/github/repositories", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -10228,7 +10561,7 @@ function registerGitHubRoutes(app, deps) {
       /\/+$/,
       ""
     );
-    const state = createSignedState3(githubStateSecret, {
+    const state = createSignedState4(githubStateSecret, {
       accountId: grant.accountId,
       workspaceId: grant.workspaceId
     });
@@ -10273,23 +10606,134 @@ function registerGitHubRoutes(app, deps) {
       throw new HTTPException16(400, { message: "missing GitHub installation state" });
     }
     const statePayload = readSignedState3(state, githubStateSecret);
-    if (!statePayload || typeof statePayload.accountId !== "string" || typeof statePayload.workspaceId !== "string") {
+    if (!statePayload || statePayload.intent !== "installation_authority" || typeof statePayload.accountId !== "string" || typeof statePayload.workspaceId !== "string" || !isFreshGitHubBindingState(statePayload)) {
       throw new HTTPException16(400, { message: "invalid or expired GitHub installation state" });
     }
-    throw installationBindingDisabled();
+    requireGitHubStateCookie(c, state);
+    const grant = await requireGitHubManageGrant(c, deps, statePayload.workspaceId, statePayload);
+    if (grant.accountId !== statePayload.accountId) {
+      throw new HTTPException16(403, {
+        message: "GitHub installation state does not match this workspace"
+      });
+    }
+    const setupAction = c.req.query("setup_action");
+    if (setupAction === "request") {
+      return c.html(githubSetupPendingHtml());
+    }
+    if (setupAction !== "install" && setupAction !== "update") {
+      throw new HTTPException16(400, { message: "unsupported GitHub setup action" });
+    }
+    const installationId = parsePositiveInteger(c.req.query("installation_id"));
+    if (installationId === null) {
+      throw new HTTPException16(400, { message: "missing or invalid GitHub installation_id" });
+    }
+    const clientId = settings.githubClientId?.trim();
+    if (!clientId) {
+      throw new HTTPException16(409, {
+        message: JSON.stringify({
+          message: "GitHub App is not configured",
+          missing: ["OPENGENI_GITHUB_CLIENT_ID"]
+        })
+      });
+    }
+    const oauthState = createSignedState4(githubStateSecret, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      installationId,
+      intent: "installation_authority_oauth",
+      ...continuedGitHubBrowserGrantClaims(statePayload)
+    });
+    setGitHubStateCookie(c, deps, oauthState);
+    return c.redirect(
+      githubOAuthAuthorizeUrl({
+        clientId,
+        state: oauthState,
+        redirectUri: `${openGeniBaseUrl(settings, c)}/v1/github/oauth/callback`
+      })
+    );
   };
   app.get("/v1/github/setup", handleGitHubInstallCallback);
   app.get("/v1/github/install/callback", handleGitHubInstallCallback);
   app.get("/v1/github/oauth/callback", async (c) => {
+    const code = c.req.query("code");
     const state = c.req.query("state");
+    if (!code) {
+      throw new HTTPException16(400, { message: "missing GitHub OAuth code" });
+    }
     if (!state) {
       throw new HTTPException16(400, { message: "missing GitHub OAuth state" });
     }
     const statePayload = readSignedState3(state, githubStateSecret);
-    if (!statePayload || typeof statePayload.accountId !== "string" || typeof statePayload.workspaceId !== "string") {
+    if (!statePayload || statePayload.intent !== "installation_authority_oauth" || typeof statePayload.accountId !== "string" || typeof statePayload.workspaceId !== "string" || !isFreshGitHubBindingState(statePayload)) {
       throw new HTTPException16(400, { message: "invalid or expired GitHub OAuth state" });
     }
-    throw installationBindingDisabled();
+    const installationId = parsePositiveInteger(String(statePayload.installationId ?? ""));
+    if (installationId === null) {
+      throw new HTTPException16(400, { message: "invalid GitHub installation id" });
+    }
+    requireGitHubStateCookie(c, state);
+    const grant = await requireGitHubManageGrant(c, deps, statePayload.workspaceId, statePayload);
+    if (grant.accountId !== statePayload.accountId) {
+      throw new HTTPException16(403, {
+        message: "GitHub OAuth state does not match this workspace"
+      });
+    }
+    let proof;
+    try {
+      proof = deps.githubAppApi?.authorizeInstallationBinding ? await deps.githubAppApi.authorizeInstallationBinding({ code, installationId }) : deps.githubAppApi ? null : await authorizeGitHubInstallationBinding(settings, { code, installationId });
+    } catch (error) {
+      throw githubAuthorityHttpError(error);
+    }
+    if (!proof) {
+      throw new HTTPException16(409, {
+        message: "The configured GitHub provider cannot prove personal-owner or organization-owner authority"
+      });
+    }
+    if (!isConsistentGitHubBindingProof(proof, installationId)) {
+      throw new HTTPException16(409, { message: "GitHub installation proof is stale or invalid" });
+    }
+    const repositoryIds = [...new Set(proof.repositories.map((repository) => repository.id))];
+    if (repositoryIds.length !== proof.repositories.length) {
+      throw new HTTPException16(409, { message: "GitHub returned duplicate repository identities" });
+    }
+    const authorityCheckedAt = /* @__PURE__ */ new Date();
+    const expiresAt = new Date((statePayload.iat + githubBindingStateMaxAgeSeconds) * 1e3);
+    let bound;
+    try {
+      bound = await bindAuthorizedGitHubInstallationRepositories(db, {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        installationId,
+        githubAccountId: proof.installation.accountId,
+        accountLogin: proof.installation.accountLogin,
+        accountType: proof.installation.accountType,
+        linkedBySubjectId: grant.subjectId,
+        githubActorId: proof.actorId,
+        githubActorLogin: proof.actorLogin,
+        authorityKind: proof.authorityKind,
+        authorityCheckedAt,
+        authorityExpiresAt: expiresAt,
+        authorityNonce: statePayload.nonce,
+        repositoryIds
+      });
+    } catch (error) {
+      if (error instanceof GitHubInstallationAuthorityCommitError) {
+        throw new HTTPException16(409, { message: error.message });
+      }
+      throw error;
+    }
+    if (!bound) {
+      throw new HTTPException16(409, {
+        message: "GitHub installation authorization was already used"
+      });
+    }
+    deleteCookie(c, githubStateCookie, { path: "/v1" });
+    return c.html(
+      githubSetupSuccessHtml(
+        proof.installation.accountLogin ?? `installation ${installationId}`,
+        openGeniReturnUrl(settings, c, grant.workspaceId)
+      )
+    );
   });
   app.post("/v1/workspaces/:workspaceId/github/installations", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -10302,11 +10746,11 @@ function registerGitHubRoutes(app, deps) {
     if (!statePayload || typeof statePayload.accountId !== "string" || statePayload.accountId.length === 0 || statePayload.workspaceId !== workspaceId) {
       throw new HTTPException16(400, { message: "invalid or expired GitHub OAuth state" });
     }
-    throw installationBindingDisabled();
+    throw legacyInstallationChooserDisabled();
   });
 }
-function installationBindingDisabled() {
-  return new HTTPException16(410, { message: installationBindingDisabledMessage });
+function legacyInstallationChooserDisabled() {
+  return new HTTPException16(410, { message: legacyInstallationChooserDisabledMessage });
 }
 function setGitHubStateCookie(c, deps, state) {
   setCookie(c, githubStateCookie, state, {
@@ -10317,6 +10761,61 @@ function setGitHubStateCookie(c, deps, state) {
     maxAge: stateMaxAgeSeconds
   });
 }
+function requireGitHubStateCookie(c, state) {
+  if (!allCookieValues(c, githubStateCookie).includes(state)) {
+    throw new HTTPException16(400, {
+      message: "invalid or expired GitHub installation browser state"
+    });
+  }
+}
+async function requireGitHubManageGrant(c, deps, workspaceId, expectedState) {
+  try {
+    return await requireAccessGrant10(c, deps, workspaceId, "github:manage");
+  } catch (error) {
+    if (!(error instanceof HTTPException16) || error.status !== 401) {
+      throw error;
+    }
+    const grant = githubBrowserGrantFromState(deps.settings, expectedState, workspaceId);
+    if (grant) {
+      return grant;
+    }
+    throw error;
+  }
+}
+function allCookieValues(c, name) {
+  const prefix = `${name}=`;
+  return (c.req.header("cookie") ?? "").split(";").map((part) => part.trim()).filter((part) => part.startsWith(prefix)).map((part) => {
+    const raw = part.slice(prefix.length);
+    try {
+      return decodeURIComponent(raw);
+    } catch {
+      return raw;
+    }
+  });
+}
+function githubAuthorityHttpError(error) {
+  if (error instanceof HTTPException16) {
+    return error;
+  }
+  if (error instanceof GitHubInstallationAuthorityError) {
+    if (error.reason === "authority_denied") {
+      return new HTTPException16(403, { message: error.message });
+    }
+    if (error.reason === "installation_missing") {
+      return new HTTPException16(404, { message: error.message });
+    }
+    return new HTTPException16(409, { message: error.message });
+  }
+  if (error instanceof GitHubAppConfigurationError2) {
+    return new HTTPException16(409, {
+      message: JSON.stringify({ message: error.message, missing: error.missing })
+    });
+  }
+  if (error instanceof GitHubAppApiError) {
+    return new HTTPException16(502, { message: error.message });
+  }
+  return new HTTPException16(502, { message: "GitHub authority verification failed" });
+}
 function isSecureRequest(c, deps) {
   return deps.settings.publicBaseUrl?.startsWith("https://") || c.req.header("x-forwarded-proto") === "https" || new URL(c.req.url).protocol === "https:";
 }
@@ -10325,6 +10824,12 @@ function githubSuccessHtml(envLines) {
   const escaped = escapeHtml2(envText);
   return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>GitHub App Created</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(760px,calc(100vw - 32px));border:1px solid #27272a;border-radius:8px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px;line-height:1.2}p{margin:0 0 18px;color:#d4d4d8}.env-header{display:flex;align-items:center;justify-content:space-between;gap:12px;margin:22px 0 8px}.env-header h2{margin:0;font-size:13px;line-height:1.2;text-transform:uppercase;letter-spacing:.08em;color:#a1a1aa}pre{white-space:pre-wrap;word-break:break-word;max-height:380px;overflow:auto;background:#09090b;border:1px solid #27272a;border-radius:8px;padding:16px;font-size:13px;line-height:1.5}button{display:inline-flex;align-items:center;justify-content:center;min-height:36px;border-radius:6px;border:1px solid #3f3f46;padding:0 12px;background:#f4f4f5;color:#09090b;font:600 14px system-ui,sans-serif;cursor:pointer}button:disabled{cursor:not-allowed;opacity:.7}</style></head><body><main><h1>GitHub App created</h1><p>Add these values to .env, then restart API and worker.</p><div class="env-header"><h2>Environment variables</h2><button id="copy-env" type="button">Copy env</button></div><pre id="env-lines">${escaped}</pre><script>(()=>{const button=document.getElementById("copy-env");const env=document.getElementById("env-lines");async function copyText(text){if(navigator.clipboard&&window.isSecureContext){await navigator.clipboard.writeText(text);return;}const area=document.createElement("textarea");area.value=text;area.setAttribute("readonly","");area.style.position="fixed";area.style.inset="-9999px";document.body.append(area);area.select();document.execCommand("copy");area.remove();}button?.addEventListener("click",async()=>{try{await copyText(env?.textContent||"");button.textContent="Copied";setTimeout(()=>button.textContent="Copy env",1600);}catch{button.textContent="Copy failed";setTimeout(()=>button.textContent="Copy env",2200);}});})();</script></main></body></html>`;
 }
+function githubSetupSuccessHtml(account, returnUrl) {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>GitHub App Connected</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(640px,calc(100vw - 32px));border:1px solid #27272a;border-radius:8px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px;line-height:1.2}p{margin:0 0 18px;color:#d4d4d8}.button{display:inline-flex;align-items:center;justify-content:center;min-height:36px;border-radius:6px;border:1px solid #3f3f46;padding:0 12px;background:#f4f4f5;color:#09090b;font:600 14px system-ui,sans-serif;text-decoration:none}</style></head><body><main><h1>GitHub App connected</h1><p>${escapeHtml2(account)} is now available to this OpenGeni workspace through an explicit repository allowlist.</p><a class="button" href="${escapeHtml2(returnUrl)}">Back to OpenGeni</a></main></body></html>`;
+}
+function githubSetupPendingHtml() {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>GitHub App Requested</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(640px,calc(100vw - 32px));border:1px solid #27272a;border-radius:8px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px;line-height:1.2}p{margin:0;color:#d4d4d8}</style></head><body><main><h1>GitHub App request sent</h1><p>A GitHub organization owner must approve the installation. OpenGeni has not created a workspace binding.</p></main></body></html>`;
+}
 function parsePositiveInteger(value) {
   if (!value || !/^\d+$/.test(value)) {
     return null;
@@ -10332,6 +10837,22 @@ function parsePositiveInteger(value) {
   const parsed = Number(value);
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
 }
+function isFreshGitHubBindingState(payload) {
+  const age = Math.floor(Date.now() / 1e3) - payload.iat;
+  return age >= 0 && age < githubBindingStateMaxAgeSeconds;
+}
+function isConsistentGitHubBindingProof(proof, installationId) {
+  const installation = proof.installation;
+  if (installation.installationId !== installationId || !Number.isSafeInteger(installation.accountId) || installation.accountId <= 0 || !installation.accountLogin?.trim() || installation.suspended || !Number.isSafeInteger(proof.actorId) || proof.actorId <= 0 || !proof.actorLogin.trim() || proof.repositories.length === 0) {
+    return false;
+  }
+  if (proof.authorityKind === "personal_owner" ? installation.accountType !== "User" || proof.actorId !== installation.accountId : installation.accountType !== "Organization") {
+    return false;
+  }
+  return proof.repositories.every(
+    (repository) => Number.isSafeInteger(repository.id) && repository.id > 0 && repository.installationId === installationId && repository.accountLogin === installation.accountLogin && repository.accountType === installation.accountType
+  );
+}
 function escapeHtml2(value) {
   return value.replace(
     /[&<>"']/g,
@@ -10344,6 +10865,14 @@ function escapeHtml2(value) {
     })[char] ?? char
   );
 }
+function openGeniReturnUrl(settings, c, workspaceId) {
+  const url = new URL(openGeniBaseUrl(settings, c) || new URL(c.req.url).origin);
+  url.searchParams.set("workspaceId", workspaceId);
+  return url.toString();
+}
+function openGeniBaseUrl(settings, c) {
+  return githubBrowserBaseUrl(settings, new URL(c.req.url).origin);
+}
 
 // src/routes/packs.ts
 import {
@@ -10949,6 +11478,7 @@ import {
   UpdateSessionGoalRequest,
   UpdateSessionMcpApprovalPolicyRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   workspaceControlUtf8Bytes
@@ -10996,6 +11526,7 @@ import {
   NewSessionDraftConflictError,
   SessionCommandIdempotencyError,
   SessionControlConflictError,
+  SessionToolPolicyVersionConflictError,
   SessionContextBusyError,
   HumanInputResponseValidationError,
   latestWorkspaceCapture,
@@ -11260,6 +11791,7 @@ import {
   sessionSpawnDenialEnvelope as sessionSpawnDenialEnvelope2,
   steerHumanQueuePrompt,
   updateSessionMcpApprovalPolicy,
+  updateSessionToolPolicy,
   updateSessionTitle as updateSessionTitle2,
   workflowIdForSession,
   sessionWithEffectiveToolPolicy as sessionWithEffectiveToolPolicy2,
@@ -12311,6 +12843,28 @@ function registerSessionRoutes(app, deps) {
       );
     }
   );
+  app.put("/v1/workspaces/:workspaceId/sessions/:sessionId/tool-policy", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant14(c, deps, workspaceId, "sessions:control");
+    const sessionId = c.req.param("sessionId");
+    const payload = UpdateSessionToolPolicyRequest.parse(await c.req.json().catch(() => null));
+    try {
+      const session = await updateSessionToolPolicy(deps, grant, sessionId, payload);
+      return c.json(await withEffectivePolicy(deps, workspaceId, session));
+    } catch (error) {
+      if (error instanceof SessionToolPolicyVersionConflictError) {
+        return c.json(
+          {
+            code: error.code,
+            message: error.message,
+            currentVersion: error.currentVersion
+          },
+          409
+        );
+      }
+      throw error;
+    }
+  });
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant14(c, deps, workspaceId, "sessions:read");
@@ -13742,6 +14296,7 @@ function sessionAuthorizationOperationForHttp(method, pathname, sessionId) {
     return null;
   }
   if (suffix === "/pin" && verb === "PUT") return "session.pin.write";
+  if (suffix === "/tool-policy" && verb === "PUT") return "session.tool_policy.write";
   if (/^\/mcp-servers\/[^/]+\/approval-policy$/.test(suffix) && verb === "PATCH") {
     return "session.mcp.approval_policy.write";
   }
@@ -14143,7 +14698,7 @@ import {
 } from "@opengeni/db";
 import { boundWorkspaceControlHttpPage } from "@opengeni/events";
 import { HTTPException as HTTPException23 } from "hono/http-exception";
-import { hasPermission as hasPermission4, requireAccessContext as requireAccessContext2, requireAccessGrant as requireAccessGrant16 } from "@opengeni/core";
+import { hasPermission as hasPermission6, requireAccessContext as requireAccessContext2, requireAccessGrant as requireAccessGrant16 } from "@opengeni/core";
 import { requireLimit as requireLimit7 } from "@opengeni/core";
 import {
   assertWorkspaceDeletable,
@@ -14390,7 +14945,7 @@ function registerWorkspaceRoutes(app, deps) {
     const context = await requireAccessContext2(c, deps);
     const readableWorkspaceIds = [
       ...new Set(
-        context.workspaceGrants.filter((grant) => hasPermission4(grant.permissions, "workspace:read")).map((grant) => grant.workspaceId)
+        context.workspaceGrants.filter((grant) => hasPermission6(grant.permissions, "workspace:read")).map((grant) => grant.workspaceId)
       )
     ];
     if (readableWorkspaceIds.length > 0) {
@@ -14664,6 +15219,7 @@ import {
 } from "@opengeni/core";
 import { workflowIdForSession as workflowIdForSession2 } from "@opengeni/core";
 var API_MAX_REQUEST_BODY_BYTES = 8 * 1024 * 1024;
+var API_PUBLIC_ERROR_MESSAGE_MAX_BYTES = 512;
 function createApp(deps) {
   const managedAuth = deps.managedAuth ?? createManagedAuth(deps.settings, deps.db);
   const objectStorage = deps.objectStorage === void 0 ? createObjectStorage(deps.settings) : deps.objectStorage;
@@ -14717,6 +15273,13 @@ function createApp(deps) {
     resumeBoxById
   };
   const app = new Hono();
+  const correlationIds = /* @__PURE__ */ new WeakMap();
+  app.use("*", async (c, next) => {
+    const correlationId = boundedCorrelationId(c.req.header(OPENGENI_CORRELATION_HEADER)) ?? crypto.randomUUID();
+    correlationIds.set(c.req.raw, correlationId);
+    c.header(OPENGENI_CORRELATION_HEADER, correlationId);
+    await next();
+  });
   app.use(
     "*",
     cors({
@@ -14727,9 +15290,10 @@ function createApp(deps) {
         "Content-Type",
         "X-OpenGeni-Access-Key",
         "X-OpenGeni-Api-Contract",
+        "X-OpenGeni-Correlation-Id",
         "X-OpenGeni-Subject"
       ],
-      exposeHeaders: ["X-OpenGeni-Api-Contract"],
+      exposeHeaders: ["X-OpenGeni-Api-Contract", "X-OpenGeni-Correlation-Id"],
       origin: (origin) => {
         if (!origin) {
           return null;
@@ -14748,6 +15312,7 @@ function createApp(deps) {
   app.use("*", async (c, next) => {
     const url = new URL(c.req.url);
     const route = routeLabel(url.pathname);
+    const correlationId = correlationIds.get(c.req.raw) ?? crypto.randomUUID();
     const start = performance.now();
     const span = observability.startSpan(`HTTP ${c.req.method} ${route}`, {
       "http.request.method": c.req.method,
@@ -14776,10 +15341,12 @@ function createApp(deps) {
         status,
         durationMs: Math.round(durationSeconds * 1e3),
         traceId: span.traceId,
-        spanId: span.spanId
+        spanId: span.spanId,
+        correlationId
       });
     } catch (error) {
       const status = httpStatusForError(error);
+      const errorCode = errorCodeForStatus(status);
       const durationSeconds = (performance.now() - start) / 1e3;
       observability.recordHttpRequest({
         method: c.req.method,
@@ -14787,6 +15354,11 @@ function createApp(deps) {
         status,
         durationSeconds
       });
+      observability.incrementCounter({
+        name: "opengeni_http_errors_total",
+        help: "Total OpenGeni HTTP request failures by bounded route, status, and stable code.",
+        labels: { route, status: String(status), code: errorCode }
+      });
       span.end({
         attributes: {
           "http.response.status_code": status,
@@ -14801,7 +15373,9 @@ function createApp(deps) {
         durationMs: Math.round(durationSeconds * 1e3),
         traceId: span.traceId,
         spanId: span.spanId,
-        error: error instanceof Error ? error.message : String(error)
+        correlationId,
+        errorCode,
+        errorClass: error instanceof Error ? error.name : "NonErrorThrown"
       });
       throw error;
     }
@@ -14958,11 +15532,46 @@ function createApp(deps) {
   registerSessionRoutes(app, routeDeps);
   registerScheduledTaskRoutes(app, routeDeps);
   registerCodexRoutes(app, routeDeps);
+  app.notFound((c) => {
+    if (!new URL(c.req.url).pathname.startsWith("/v1/")) return c.text("Not Found", 404);
+    const requestId = correlationIds.get(c.req.raw) ?? crypto.randomUUID();
+    return c.json(
+      ErrorEnvelope.parse({
+        error: {
+          status: 404,
+          code: "not_found",
+          message: "Resource not found.",
+          retryable: false,
+          requestId
+        }
+      }),
+      404
+    );
+  });
+  app.onError((error, c) => {
+    const status = httpStatusForError(error);
+    const code = errorCodeForStatus(status);
+    const requestId = correlationIds.get(c.req.raw) ?? crypto.randomUUID();
+    c.header(OPENGENI_CORRELATION_HEADER, requestId);
+    if (new URL(c.req.url).pathname.startsWith("/v1/")) {
+      c.header(OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION);
+    }
+    const envelope = ErrorEnvelope.parse({
+      error: {
+        status,
+        code,
+        message: publicErrorMessage(error, status),
+        retryable: retryableHttpStatus(status),
+        requestId
+      }
+    });
+    return c.json(envelope, status);
+  });
   return app;
 }
 async function requireMcpAccessGrant(c, deps, workspaceId) {
   const grant = await requireAccessGrant17(c, deps, workspaceId);
-  if (hasPermission5(grant.permissions, "workspace:read")) {
+  if (hasPermission7(grant.permissions, "workspace:read")) {
     return grant;
   }
   if (isToolspaceGrant(deps.settings, grant)) {
@@ -15006,6 +15615,45 @@ function httpStatusForError(error) {
   }
   return 500;
 }
+function errorCodeForStatus(status) {
+  if (status === 401) return "unauthenticated";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 413 || status === 422 || status === 400) return "validation_failed";
+  if (status === 429) return "limit_exceeded";
+  if (status === 502 || status === 503 || status === 504) return "upstream_unavailable";
+  return "internal_error";
+}
+function retryableHttpStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function publicErrorMessage(error, status) {
+  if (status === 502 || status === 503 || status === 504) {
+    return "OpenGeni is temporarily unavailable \u2014 retry.";
+  }
+  if (status >= 500) {
+    return "OpenGeni could not complete the request.";
+  }
+  if (error instanceof HTTPException24) {
+    return boundedPublicMessage(error.message) ?? "Request failed.";
+  }
+  if (error instanceof McpPayloadTooLargeError2) {
+    return "Request payload is too large.";
+  }
+  return "Request failed.";
+}
+function boundedPublicMessage(value) {
+  const normalized = value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  if (!normalized) return null;
+  const bytes = new TextEncoder().encode(normalized);
+  if (bytes.byteLength <= API_PUBLIC_ERROR_MESSAGE_MAX_BYTES) return normalized;
+  return new TextDecoder().decode(bytes.slice(0, API_PUBLIC_ERROR_MESSAGE_MAX_BYTES)).trim();
+}
+function boundedCorrelationId(value) {
+  if (!value || value.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(value)) return null;
+  return value;
+}
 function readinessChecks(deps) {
   return {
     db: deps.readinessChecks?.db ?? (async () => {
@@ -15444,6 +16092,7 @@ export {
   createApp,
   allowedCorsOrigin,
   httpStatusForError,
+  errorCodeForStatus,
   routeLabel,
   isApiContractProtectedMutation,
   mergeResourceRefs,
@@ -15457,4 +16106,4 @@ export {
   withDefaultEnabledCapabilityMcpTools,
   workflowIdForSession2 as workflowIdForSession
 };
-//# sourceMappingURL=chunk-BFWSDESE.js.map
+//# sourceMappingURL=chunk-DQWFAIPE.js.map