@opengeni/api-router 0.12.7 → 0.14.3

package/src/routes/transcriptions.ts

@@ -0,0 +1,155 @@
+import {
+  resolveWorkspaceVoiceInputEnabled,
+  type TranscribeAudioResponse,
+} from "@opengeni/contracts";
+import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
+import { getWorkspace } from "@opengeni/db";
+import type { Hono } from "hono";
+
+export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.post("/v1/workspaces/:workspaceId/transcriptions", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const workspace = await getWorkspace(deps.db, workspaceId);
+    if (!workspace) return c.json({ code: "not_found" }, 404);
+    if (resolveWorkspaceVoiceInputEnabled(workspace.settings) === false) {
+      return c.json({ code: "policy_blocked" }, 403);
+    }
+    const service = deps.transcription;
+    if (!service || !(await service.available())) {
+      return c.json({ code: "unavailable" }, 503);
+    }
+    try {
+      const body = await audioRequest(c.req.raw, service.limits().maxSizeBytes);
+      const result = await service.transcribe({
+        workspaceId,
+        accountId: grant.accountId,
+        audio: body.audio,
+        mimeType: body.mimeType,
+        durationSeconds: body.durationSeconds,
+        signal: c.req.raw.signal,
+        requestId: c.req.header("x-opengeni-correlation-id") ?? crypto.randomUUID(),
+      });
+      const response: TranscribeAudioResponse = {
+        text: result.text,
+        languages: result.languages,
+      };
+      return c.json(response);
+    } catch (error) {
+      if (error instanceof TranscriptionServiceError) {
+        return c.json({ code: error.code }, error.status as never);
+      }
+      if (isAbort(error)) return c.json({ code: "cancelled" }, 499 as never);
+      return c.json({ code: "unknown" }, 500);
+    }
+  });
+}
+
+async function audioRequest(
+  request: Request,
+  maxSizeBytes: number,
+): Promise<{ audio: Uint8Array; mimeType: string; durationSeconds?: number }> {
+  const contentLength = Number(request.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > maxSizeBytes + 64 * 1024) {
+    throw new TranscriptionServiceError({
+      code: "too_large",
+      message: "Audio is too large.",
+    });
+  }
+  const contentType = request.headers.get("content-type") ?? "";
+  if (contentType.toLowerCase().startsWith("multipart/form-data")) {
+    const form = await request.formData();
+    const audio = form.get("audio");
+    if (!(audio instanceof File)) {
+      throw new TranscriptionServiceError({
+        code: "invalid_audio",
+        message: "Audio file is required.",
+      });
+    }
+    if (audio.size > maxSizeBytes) {
+      throw new TranscriptionServiceError({
+        code: "too_large",
+        message: "Audio is too large.",
+      });
+    }
+    const durationSeconds = durationValue(stringValue(form.get("durationSeconds")));
+    return {
+      audio: new Uint8Array(await audio.arrayBuffer()),
+      mimeType: stringValue(form.get("mimeType")) ?? audio.type,
+      ...(durationSeconds === undefined ? {} : { durationSeconds }),
+    };
+  }
+  const mimeType = contentType.split(";", 1)[0]?.trim() ?? "";
+  if (!mimeType.toLowerCase().startsWith("audio/")) {
+    throw new TranscriptionServiceError({
+      code: "not_supported",
+      message: "Unsupported audio format.",
+    });
+  }
+  const durationSeconds = durationValue(request.headers.get("x-opengeni-audio-duration-seconds"));
+  return {
+    audio: await readBounded(request.body, maxSizeBytes, request.signal),
+    mimeType,
+    ...(durationSeconds === undefined ? {} : { durationSeconds }),
+  };
+}
+
+async function readBounded(
+  body: ReadableStream<Uint8Array> | null,
+  maxSizeBytes: number,
+  signal: AbortSignal,
+): Promise<Uint8Array> {
+  if (!body)
+    throw new TranscriptionServiceError({
+      code: "invalid_audio",
+      message: "Audio is required.",
+    });
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+      const next = await reader.read();
+      if (next.done) break;
+      size += next.value.byteLength;
+      if (size > maxSizeBytes) {
+        await reader.cancel();
+        throw new TranscriptionServiceError({
+          code: "too_large",
+          message: "Audio is too large.",
+        });
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const audio = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    audio.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return audio;
+}
+
+function durationValue(value: string | null | undefined): number | undefined {
+  if (value == null || value.trim() === "") return undefined;
+  const duration = Number(value);
+  if (!Number.isFinite(duration)) {
+    throw new TranscriptionServiceError({
+      code: "invalid_audio",
+      message: "Invalid audio duration.",
+    });
+  }
+  return duration;
+}
+
+function stringValue(value: FormDataEntryValue | null): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}

package/src/routes/workspace-capture.ts

@@ -38,6 +38,97 @@ export type CaptureStoragePort = {
   }) => Promise<{ url: string; expiresAt: Date }>;
 };
 
+type LoadedManifest = {
+  manifest: WorkspaceCaptureManifest;
+  byteLength: number;
+  stats: WorkspaceCaptureStats;
+};
+
+type ManifestCacheEntry = LoadedManifest & {
+  identity: string;
+  inlineResponse?: Extract<GetWorkspaceCaptureResponse, { available: true }>;
+};
+
+/**
+ * Process-local cache for immutable capture manifests. Capture rows point at a
+ * revision-specific object key, so a successfully validated blob is safe to
+ * reuse as long as the row identity still matches. Both entry count and bytes
+ * are bounded; large signed-manifest responses bypass the cache.
+ */
+export class WorkspaceCaptureManifestCache {
+  readonly #entries = new Map<string, ManifestCacheEntry>();
+  #retainedBytes = 0;
+
+  constructor(
+    readonly maxEntries = 64,
+    readonly maxBytes = 16 * 1024 * 1024,
+  ) {}
+
+  get(row: WorkspaceCaptureRow): LoadedManifest | null {
+    const key = row.manifestKey;
+    if (!key) return null;
+    const entry = this.#entries.get(key);
+    if (!entry || entry.identity !== manifestIdentity(row)) return null;
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    return entry;
+  }
+
+  getInlineResponse(
+    row: WorkspaceCaptureRow,
+  ): Extract<GetWorkspaceCaptureResponse, { available: true }> | null {
+    const key = row.manifestKey;
+    if (!key) return null;
+    const entry = this.#entries.get(key);
+    if (!entry || entry.identity !== manifestIdentity(row) || !entry.inlineResponse) return null;
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    return entry.inlineResponse;
+  }
+
+  setInlineResponse(
+    row: WorkspaceCaptureRow,
+    response: Extract<GetWorkspaceCaptureResponse, { available: true }>,
+  ): void {
+    const key = row.manifestKey;
+    if (!key) return;
+    const entry = this.#entries.get(key);
+    if (!entry || entry.identity !== manifestIdentity(row)) return;
+    entry.inlineResponse = response;
+  }
+
+  set(row: WorkspaceCaptureRow, loaded: LoadedManifest): void {
+    const key = row.manifestKey;
+    if (
+      !key ||
+      this.maxEntries <= 0 ||
+      this.maxBytes <= 0 ||
+      loaded.byteLength > CAPTURE_INLINE_MANIFEST_MAX_BYTES ||
+      loaded.byteLength > this.maxBytes
+    ) {
+      return;
+    }
+    const previous = this.#entries.get(key);
+    if (previous) {
+      this.#retainedBytes -= previous.byteLength;
+      this.#entries.delete(key);
+    }
+    this.#entries.set(key, { ...loaded, identity: manifestIdentity(row) });
+    this.#retainedBytes += loaded.byteLength;
+    while (this.#entries.size > this.maxEntries || this.#retainedBytes > this.maxBytes) {
+      const oldestKey = this.#entries.keys().next().value;
+      if (oldestKey === undefined) break;
+      const oldest = this.#entries.get(oldestKey);
+      this.#entries.delete(oldestKey);
+      if (oldest) this.#retainedBytes -= oldest.byteLength;
+    }
+  }
+}
+
+function manifestIdentity(row: WorkspaceCaptureRow): string {
+  return `${row.sessionId}\0${row.turnId}\0${row.revision}\0${row.leaseEpoch}\0${row.capturedAt}`;
+}
+
 function signedUrl(signed: { url: string; expiresAt: Date }): { url: string; expiresAt: string } {
   return { url: signed.url, expiresAt: signed.expiresAt.toISOString() };
 }
@@ -51,12 +142,11 @@ function signedUrl(signed: { url: string; expiresAt: Date }): { url: string; exp
 async function loadManifest(
   row: WorkspaceCaptureRow,
   storage: CaptureStoragePort,
-): Promise<{
-  manifest: WorkspaceCaptureManifest;
-  byteLength: number;
-  stats: WorkspaceCaptureStats;
-} | null> {
+  cache?: WorkspaceCaptureManifestCache,
+): Promise<LoadedManifest | null> {
   if (!row.manifestKey) return null;
+  const cached = cache?.get(row);
+  if (cached) return cached;
   const stats = WorkspaceCaptureStats.safeParse(row.stats);
   if (!stats.success) {
     console.warn(
@@ -114,7 +204,9 @@ async function loadManifest(
     );
     return null;
   }
-  return { manifest, byteLength: blob.bytes.byteLength, stats: servedStats };
+  const loaded = { manifest, byteLength: blob.bytes.byteLength, stats: servedStats };
+  cache?.set(row, loaded);
+  return loaded;
 }
 
 /**
@@ -126,6 +218,7 @@ async function loadManifest(
 export async function serveWorkspaceCapture(
   row: WorkspaceCaptureRow | null,
   storage: CaptureStoragePort,
+  cache?: WorkspaceCaptureManifestCache,
 ): Promise<GetWorkspaceCaptureResponse> {
   if (!row) {
     return { available: false };
@@ -148,11 +241,13 @@ export async function serveWorkspaceCapture(
     });
   }
   if (row.state !== "available" || !row.manifestKey) return { available: false };
+  const cachedResponse = cache?.getInlineResponse(row);
+  if (cachedResponse) return cachedResponse;
   // Validate every manifest before serving it, including the rare >2MB signed
   // path. Previously that branch signed arbitrary bytes merely because they
   // exceeded the inline cap, allowing a poison/mis-keyed blob to bypass both the
   // schema and row-identity checks.
-  const loaded = await loadManifest(row, storage);
+  const loaded = await loadManifest(row, storage, cache);
   if (!loaded) return { available: false };
   const meta = {
     available: true as const,
@@ -164,11 +259,16 @@ export async function serveWorkspaceCapture(
     stats: loaded.stats,
   };
   if (loaded.byteLength <= CAPTURE_INLINE_MANIFEST_MAX_BYTES) {
-    return GetWorkspaceCaptureResponse.parse({
+    const response = GetWorkspaceCaptureResponse.parse({
       ...meta,
       manifest: loaded.manifest,
       manifestUrl: null,
     });
+    if (!response.available) {
+      throw new Error("validated inline capture response lost its available discriminator");
+    }
+    cache?.setInlineResponse(row, response);
+    return response;
   }
   const signed = await storage.createGetUrl({
     key: row.manifestKey,

package/src/routes/workspace-state.ts

@@ -0,0 +1,61 @@
+import {
+  WORKSPACE_STATE_MAX_BASES,
+  WORKSPACE_STATE_MAX_TOPICS,
+  WORKSPACE_STATE_TOPIC_MAX_CHARS,
+  WorkspaceStateResponse,
+} from "@opengeni/contracts";
+import { hasPermission, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  getWorkspace,
+  listWorkspaceStateMemoryRecords,
+  listWorkspaceInstructionPolicyRevisions,
+} from "@opengeni/db";
+import { getDocumentInventory } from "@opengeni/documents";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+import { projectWorkspaceState } from "../workspace-state-projection";
+
+export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get("/v1/workspaces/:workspaceId/workspace-state", async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const generatedAt = new Date().toISOString();
+    const canInspectKnowledge = hasPermission(grant.permissions, "documents:search");
+
+    const [workspace, policies, knowledge] = await Promise.all([
+      getWorkspace(deps.db, workspaceId),
+      listWorkspaceInstructionPolicyRevisions(deps.db, workspaceId, { limit: 1 }),
+      canInspectKnowledge
+        ? (async () => {
+            const [documents, memories] = await Promise.all([
+              getDocumentInventory(deps.db, workspaceId, {
+                baseLimit: WORKSPACE_STATE_MAX_BASES,
+                topicLimit: WORKSPACE_STATE_MAX_TOPICS,
+                topicMaxChars: WORKSPACE_STATE_TOPIC_MAX_CHARS,
+                access: { viewerSubjectId: grant.subjectId },
+              }),
+              listWorkspaceStateMemoryRecords(deps.db, workspaceId),
+            ]);
+            return { documents, memories };
+          })()
+        : Promise.resolve(null),
+    ]);
+
+    if (!workspace) {
+      throw new HTTPException(404, { message: "workspace not found" });
+    }
+    context.header("cache-control", "private, no-store");
+    return context.json(
+      WorkspaceStateResponse.parse(
+        projectWorkspaceState({
+          workspaceId,
+          generatedAt,
+          workspaceAgentInstructions: workspace.agentInstructions,
+          policies,
+          knowledge,
+        }),
+      ),
+    );
+  });
+}

package/src/sandbox/channel-a.ts

@@ -21,6 +21,7 @@ import {
   applyGitAuthPointerEnvironment,
   hasGitCredentialRepositorySelection,
   hasGitHubRepositorySelection,
+  sandboxArchiveCaptureTimeoutMs,
   stableSandboxEnvironmentForRun,
   type Settings,
 } from "@opengeni/config";
@@ -247,6 +248,7 @@ export async function withChannelA<T>(
     os: session.sandboxOs,
     leaseTtlMs,
     warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
+    captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
   });
 
   if (acquired.role === "blocked") {

package/src/sandbox/rematerialize.ts

@@ -1,5 +1,6 @@
 import type { Settings } from "@opengeni/config";
 import {
+  adoptLegacyModalCheckpointArtifact,
   beginSandboxRematerialization,
   commitWarmingToWarm,
   failSandboxRematerialization,
@@ -12,9 +13,13 @@ import {
   type LeaseSnapshot,
 } from "@opengeni/db";
 import {
+  describeLegacyNativeSnapshotArchive,
   establishSandboxSessionFromEnvelope,
   isProviderSandboxNotFoundError,
+  modalSessionMatchesCheckpointProviderBinding,
+  parseWorkspaceArchiveDescriptor,
   requirePersistableReplacementSandboxEnvelope,
+  resolveModalCheckpointProviderBindingForSession,
   serializeReplacementSandboxEnvelope,
   tagModalSandbox,
   verifySandboxExecReadiness,
@@ -33,6 +38,20 @@ function hasWorkspaceArchive(envelope: Record<string, unknown> | null): boolean
   );
 }
 
+function legacyNativeArchiveFromEnvelope(envelope: Record<string, unknown> | null) {
+  const sessionState =
+    envelope?.sessionState && typeof envelope.sessionState === "object"
+      ? (envelope.sessionState as Record<string, unknown>)
+      : null;
+  if (!sessionState) return null;
+  const existing = parseWorkspaceArchiveDescriptor(sessionState.workspaceArchiveMeta);
+  if (existing?.version === 2) return null;
+  return describeLegacyNativeSnapshotArchive(
+    sessionState.workspaceArchive,
+    existing?.version === 1 ? Date.parse(existing.capturedAt) : Date.now(),
+  );
+}
+
 function withoutProviderIdentity(
   envelope: Record<string, unknown> | null,
 ): Record<string, unknown> | null {
@@ -48,7 +67,9 @@ function withoutProviderIdentity(
 
 async function terminateCreated(established: EstablishedSandboxSession | null): Promise<boolean> {
   if (!established) return true;
-  const client = established.client as { delete?: (state: unknown) => Promise<unknown> };
+  const client = established.client as {
+    delete?: (state: unknown) => Promise<unknown>;
+  };
   try {
     if (typeof client.delete === "function" && established.sessionState !== undefined) {
       await client.delete(established.sessionState);
@@ -93,20 +114,30 @@ export async function establishApiSandboxSpawner(input: {
     hasWorkspaceArchive(input.fallbackEnvelope)
       ? withoutProviderIdentity(input.fallbackEnvelope)
       : null;
-  const spawnEnvelope =
+  let spawnEnvelope =
     fallbackArchiveEnvelope ?? input.acquiredLease.resumeState ?? input.fallbackEnvelope;
   const archiveSource =
     input.acquiredLease.recovery.archive.status === "none"
       ? fallbackArchiveEnvelope
       : input.acquiredLease.resumeState;
   let established: EstablishedSandboxSession | null = null;
-  let rematerialization: { id: string; selectedRevision: string } | null = null;
+  let rematerialization: {
+    id: string;
+    selectedRevision: string;
+    workspaceGeneration: number;
+    providerBindingKey: string | null;
+    legacyCheckpoint: ReturnType<typeof legacyNativeArchiveFromEnvelope>;
+    legacyProviderBinding: Awaited<
+      ReturnType<typeof resolveModalCheckpointProviderBindingForSession>
+    > | null;
+  } | null = null;
   try {
     if (
       input.acquiredLease.recovery.archive.status === "available" ||
       hasWorkspaceArchive(archiveSource)
     ) {
       const id = crypto.randomUUID();
+      const legacyNativeArchive = legacyNativeArchiveFromEnvelope(archiveSource);
       const begun = await beginSandboxRematerialization(input.db, {
         accountId: input.accountId,
         workspaceId: input.workspaceId,
@@ -114,6 +145,7 @@ export async function establishApiSandboxSpawner(input: {
         expectedEpoch: input.expectedEpoch,
         rematerializationId: id,
         archiveSource,
+        legacyNativeArchive,
       });
       if (begun.status !== "started") {
         if (begun.code === "stale_epoch" || begun.code === "attempt_conflict") {
@@ -129,6 +161,7 @@ export async function establishApiSandboxSpawner(input: {
           begun.lease?.recovery ?? input.acquiredLease.recovery,
         );
       }
+      spawnEnvelope = begun.lease.resumeState ?? spawnEnvelope;
       const selectedRevision = begun.lease.recovery.restore.selectedRevision;
       if (!selectedRevision) {
         throw new WorkspaceArchiveIntegrityError(
@@ -136,7 +169,14 @@ export async function establishApiSandboxSpawner(input: {
           "sandbox rematerialization selected no durable archive revision",
         );
       }
-      rematerialization = { id, selectedRevision };
+      rematerialization = {
+        id,
+        selectedRevision,
+        workspaceGeneration: begun.lease.workspaceGeneration,
+        providerBindingKey: begun.checkpointArtifact?.providerBindingKey ?? null,
+        legacyCheckpoint: begun.checkpointArtifact === null ? legacyNativeArchive : null,
+        legacyProviderBinding: null,
+      };
     } else if (input.acquiredLease.recovery.archive.status !== "none") {
       throw new SandboxLeaseRecoveryBlockedError(
         input.sandboxGroupId,
@@ -146,6 +186,7 @@ export async function establishApiSandboxSpawner(input: {
       );
     }
 
+    const providerCreateStartedAt = new Date();
     established = await establishSandboxSessionFromEnvelope(input.settings, spawnEnvelope, {
       sessionId: input.sessionId,
       recovery: "create-or-restore",
@@ -153,6 +194,37 @@ export async function establishApiSandboxSpawner(input: {
       environment: input.environment,
       onSandboxCreated: async (created) => {
         established = created;
+        if (
+          rematerialization &&
+          (rematerialization.providerBindingKey || rematerialization.legacyCheckpoint)
+        ) {
+          if (created.backendId !== "modal") {
+            throw new WorkspaceArchiveIntegrityError(
+              "native_snapshot_reference_invalid",
+              "Modal checkpoint restore resolved a non-Modal sandbox backend",
+            );
+          }
+          if (rematerialization.providerBindingKey) {
+            if (
+              !(await modalSessionMatchesCheckpointProviderBinding(
+                input.settings,
+                created.session,
+                rematerialization.providerBindingKey,
+              ))
+            ) {
+              throw new WorkspaceArchiveIntegrityError(
+                "native_snapshot_reference_invalid",
+                "Modal checkpoint restore refused because the authenticated provider workspace changed",
+              );
+            }
+          } else {
+            rematerialization.legacyProviderBinding =
+              await resolveModalCheckpointProviderBindingForSession(
+                input.settings,
+                created.session,
+              );
+          }
+        }
         const resumeState = requirePersistableReplacementSandboxEnvelope(
           await serializeReplacementSandboxEnvelope(created, spawnEnvelope),
           created.backendId,
@@ -166,6 +238,14 @@ export async function establishApiSandboxSpawner(input: {
           instanceId: created.instanceId,
           resumeBackendId: created.backendId,
           resumeState,
+          ...(created.backendId === "modal"
+            ? {
+                providerCreatedAt: providerCreateStartedAt,
+                providerDeadlineAt: new Date(
+                  providerCreateStartedAt.getTime() + input.settings.modalTimeoutSeconds * 1000,
+                ),
+              }
+            : {}),
           leaseTtlMs: input.settings.sandboxLeaseTtlMs,
           warmingLeaseTtlMs: input.settings.sandboxWarmingTimeoutMs,
         });
@@ -187,6 +267,33 @@ export async function establishApiSandboxSpawner(input: {
             `hydrated archive revision ${descriptor.revision} does not match the selected rematerialization revision`,
           );
         }
+        if (rematerialization.legacyCheckpoint) {
+          const binding = rematerialization.legacyProviderBinding;
+          if (!binding) {
+            throw new WorkspaceArchiveIntegrityError(
+              "native_snapshot_reference_invalid",
+              "Legacy Modal checkpoint restore produced no authenticated provider identity",
+            );
+          }
+          const adopted = await adoptLegacyModalCheckpointArtifact(input.db, {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sandboxGroupId: input.sandboxGroupId,
+            leaseId: input.acquiredLease.id,
+            leaseEpoch: input.expectedEpoch,
+            workspaceGeneration: rematerialization.workspaceGeneration,
+            slot: "current",
+            archiveBase64: rematerialization.legacyCheckpoint.archiveBase64,
+            descriptor: rematerialization.legacyCheckpoint.descriptor,
+            providerBindingKey: binding.key,
+            providerBinding: binding.binding,
+            rematerializationId: rematerialization.id,
+          });
+          if (!adopted) {
+            throw new SandboxLeaseSupersededError(input.sandboxGroupId, input.expectedEpoch);
+          }
+          rematerialization.providerBindingKey = binding.key;
+        }
         const verifying = await markSandboxRestoreVerifying(input.db, {
           accountId: input.accountId,
           workspaceId: input.workspaceId,

package/src/sandbox/viewer.ts

@@ -24,6 +24,7 @@ import {
   hasGitCredentialRepositorySelection,
   hasGitHubRepositorySelection,
   resolveStreamTokenSecret,
+  sandboxArchiveCaptureTimeoutMs,
   stableSandboxEnvironmentForRun,
 } from "@opengeni/config";
 import type { Settings } from "@opengeni/config";
@@ -42,6 +43,7 @@ import {
   recordLeaseTerminalDataPlaneUrl,
   releaseLeaseHolder,
   SandboxLeaseSupersededError,
+  SandboxViewerAdmissionBlockedError,
   type Database,
   type LeaseSnapshot,
   type SandboxRecord,
@@ -195,18 +197,33 @@ export async function attachViewer(
     });
   };
 
-  const acquired = await acquireLease(db, {
-    accountId,
-    workspaceId,
-    sandboxGroupId,
-    kind: "viewer",
-    holderId: viewerId,
-    subjectId: session.id,
-    backend: session.sandboxBackend,
-    os: session.sandboxOs,
-    leaseTtlMs,
-    warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
-  });
+  let acquired: Awaited<ReturnType<typeof acquireLease>>;
+  try {
+    acquired = await acquireLease(db, {
+      accountId,
+      workspaceId,
+      sandboxGroupId,
+      kind: "viewer",
+      holderId: viewerId,
+      subjectId: session.id,
+      backend: session.sandboxBackend,
+      os: session.sandboxOs,
+      leaseTtlMs,
+      warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
+      captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
+    });
+  } catch (error) {
+    if (error instanceof SandboxViewerAdmissionBlockedError) {
+      throw new HTTPException(error.reason === "balance" ? 402 : 429, {
+        message:
+          error.reason === "balance"
+            ? "insufficient OpenGeni credits for an idle sandbox viewer"
+            : "workspace sandbox warm allowance exhausted",
+        cause: error,
+      });
+    }
+    throw error;
+  }
 
   // FENCED: a newer epoch re-established the box. Release our just-registered
   // holder and surface a 409 — the client re-reads capabilities and re-attaches.