@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/codex-session-pointers.ts

@@ -0,0 +1,80 @@
+// The legacy Codex session pointers (`codexPinnedCredentialId`,
+// `codexLastCredentialId`, and `codexCurrentSelection` when the Session
+// carries it) of every Session a response returns, by the organization's
+// Codex cutover disposition (M3 PR 2b; current selection M3 PR 3):
+// - core (enabled row): the session's core binding (explicit choice and bound
+//   connection) and the active Codex turn's live core lease (or explicit
+//   choice while it waits); a session without a Codex binding shows nulls;
+// - maintenance (missing or disabled row): nulls, never the legacy ids.
+// A session read never fails because of Codex state: if the disposition or the
+// bindings cannot be read, the pointers show nulls.
+import {
+  getSubscriptionCoreCodexCurrentSelections,
+  getSubscriptionCoreCodexSessionPointers,
+  readCodexCutoverDisposition,
+  type Database,
+} from "@opengeni/db";
+
+type CodexPointerFields = {
+  id: string;
+  accountId: string;
+  codexPinnedCredentialId: string | null;
+  codexLastCredentialId: string | null;
+  codexCurrentSelection?: { credentialId: string | null; waiting: boolean } | null | undefined;
+};
+
+/** Projects one Session's public Codex pointer fields from the core. */
+export type CodexSessionPointerProjection = <T extends CodexPointerFields>(session: T) => T;
+
+const unchanged: CodexSessionPointerProjection = (session) => session;
+
+/**
+ * Load the projection once for every Session a response returns (all from one
+ * workspace). Missing cutover state is maintenance, not historical fallback.
+ */
+export async function loadCodexSessionPointerProjection(
+  db: Database,
+  workspaceId: string,
+  sessions: readonly CodexPointerFields[],
+): Promise<CodexSessionPointerProjection> {
+  const accountId = sessions[0]?.accountId;
+  if (!accountId) return unchanged;
+  let pointers: Map<string, { pinnedCredentialId: string | null; lastCredentialId: string | null }>;
+  let selections: Map<string, { credentialId: string | null; waiting: boolean }>;
+  try {
+    const disposition = await readCodexCutoverDisposition(db, accountId, workspaceId);
+    const sessionIds = sessions.map((session) => session.id);
+    [pointers, selections] =
+      disposition === "core"
+        ? await Promise.all([
+            getSubscriptionCoreCodexSessionPointers(db, { accountId, workspaceId, sessionIds }),
+            sessions.some((session) => session.codexCurrentSelection !== undefined)
+              ? getSubscriptionCoreCodexCurrentSelections(db, {
+                  accountId,
+                  workspaceId,
+                  sessionIds,
+                })
+              : Promise.resolve(new Map()),
+          ])
+        : [new Map(), new Map()];
+  } catch (error) {
+    console.warn("Codex session pointers unavailable; showing none", {
+      workspaceId,
+      error: error instanceof Error ? error.name : typeof error,
+    });
+    pointers = new Map();
+    selections = new Map();
+  }
+  return <T extends CodexPointerFields>(session: T): T => {
+    const pointer = pointers.get(session.id);
+    return {
+      ...session,
+      codexPinnedCredentialId: pointer?.pinnedCredentialId ?? null,
+      codexLastCredentialId: pointer?.lastCredentialId ?? null,
+      // A field the Session does not carry stays absent.
+      ...(session.codexCurrentSelection === undefined
+        ? {}
+        : { codexCurrentSelection: selections.get(session.id) ?? null }),
+    };
+  };
+}

package/src/company-brain-okf.ts

@@ -316,7 +316,7 @@ export function serializeCompanyBrainOkf(value: CompanyBrainOkfPackageType): str
   const parsed = CompanyBrainOkfPackage.parse(value);
   return [
     OKF_MARKER,
-    "# OpenGeni Company Brain",
+    "# Opengeni Company Brain",
     "",
     "This permission-filtered package is portable evidence. Postgres remains canonical.",
     "",

package/src/connected-machine-computer-access.ts

@@ -26,7 +26,8 @@ export function connectedMachineComputerAccessError(
   if (requiresControl && !state.allowScreenControl) {
     return {
       status: 403,
-      message: "Screen control is not enabled for this Connected Machine.",
+      message:
+        "Screen control is not enabled for this Connected Machine. Turn it on in place with connected_machine_enable_screen_control (no reconnect or human click needed), then retry.",
     };
   }
   return null;

package/src/connection-ownership.ts

@@ -1,14 +1,27 @@
 import type { ConnectionOwnership } from "@opengeni/contracts";
 import {
   externalActorContinuationForAuthorization,
+  isVerifiedDelegatedHumanAuthorization,
   type AccessGrantAuthorization,
 } from "@opengeni/core";
 import { HTTPException } from "hono/http-exception";
 
+/** Signing in to a third-party provider is the person's own step in the
+ * browser; an agent acting as them through the organization MCP server is told
+ * to finish it there. */
+export function requireProviderConsentInBrowser(access: AccessGrantAuthorization): void {
+  if (isVerifiedDelegatedHumanAuthorization(access))
+    throw new HTTPException(403, {
+      message:
+        "Signing in to a provider has to be done by the person in the Opengeni app in a browser.",
+    });
+}
+
 /** A verified external actor must not enter a native callback that has no
  * corresponding key/identity reauthorization proof. Remove at an entry point
  * only when that provider's signed continuation and commit fence are wired. */
 export function requireLegacyOAuthActor(access: AccessGrantAuthorization): void {
+  requireProviderConsentInBrowser(access);
   if (externalActorContinuationForAuthorization(access))
     throw new HTTPException(422, {
       message: "This provider does not yet support external-user OAuth continuation",
@@ -37,9 +50,9 @@ export function requireLegacyOAuthActor(access: AccessGrantAuthorization): void
  */
 
 /**
- * Subject namespaces OpenGeni itself mints for machines. This is deliberately
+ * Subject namespaces Opengeni itself mints for machines. This is deliberately
  * NOT an allow-list of human subjects: `docs/embedding.md` states that
- * `subjectId` "remains opaque to OpenGeni" and that the kind must not be
+ * `subjectId` "remains opaque to Opengeni" and that the kind must not be
  * inferred from a subject-id prefix "because the host owns that namespace", so
  * a trusted embedding host legitimately signs `human_session` over an opaque
  * subject that is not `user:`-prefixed. Restricting personal ownership to
@@ -49,7 +62,7 @@ export function requireLegacyOAuthActor(access: AccessGrantAuthorization): void
  * The allow-list that actually decides is `principalKind === "human_session"`.
  * This list is defence-in-depth against exactly one residual threat: a holder
  * of the first-party delegation secret signing a human claim over an
- * OpenGeni-minted machine subject.
+ * Opengeni-minted machine subject.
  *
  * `connection-ownership.test.ts` asserts that every machine subject named in
  * its list is rejected. Note what that does and does not buy: it catches a
@@ -85,13 +98,7 @@ const RESERVED_MACHINE_SUBJECT_NAMESPACES = [
 export function isPersonalConnectionOwnerPrincipal(access: AccessGrantAuthorization): boolean {
   const { grant } = access;
   return (
-    // The anti-substitution invariant `requireConnectionAuthorityOwner` uses for
-    // the same question: every context grant agrees on principal kind, delegated
-    // flag and service flags, and the selected grant's account resolves to
-    // exactly one matching account grant. Without it a grant whose account has
-    // no matching account grant (a surviving membership row in an organization
-    // where the membership is no longer active) could mint a personal
-    // Connection that the sibling helper would refuse.
+    // Every context grant must agree on the authenticated principal and account.
     access.contextIntegrity &&
     access.authenticatedSubjectId === grant.subjectId &&
     grant.principalKind === "human_session" &&
@@ -101,7 +108,7 @@ export function isPersonalConnectionOwnerPrincipal(access: AccessGrantAuthorizat
   );
 }
 
-/** Rejects an OpenGeni-minted machine subject; see the namespace list's rationale. */
+/** Rejects an Opengeni-minted machine subject; see the namespace list's rationale. */
 export function isPersonalConnectionOwnerSubject(subjectId: string): boolean {
   const separator = subjectId.indexOf(":");
   if (separator < 0) {
@@ -132,8 +139,7 @@ export function personalOnlyConnectionPrincipalMessage(label: string): string {
  * rejects every reserved machine-subject namespace as defence-in-depth. The
  * sibling guards a self-service authority surface where the caller claims to
  * *be* the owner (403 "not you"), while this one rejects an ownership *value*
- * that is unavailable to the caller, alongside `assertOwnershipAllowed`'s
- * existing 422 convention.
+ * that is unavailable to the caller (422).
  */
 export function assertPersonalConnectionOwnerPrincipal(
   access: AccessGrantAuthorization,

package/src/controller-data-plane.ts

@@ -6,6 +6,8 @@ import {
   parseOpenSandboxSignedUriPath,
   signedEndpointNeedsRefresh,
 } from "@opengeni/runtime/sandbox";
+import type { InteractionPlacement } from "@opengeni/contracts";
+import type { ChannelAOperation } from "./sandbox/channel-a";
 
 /** Modal/Daytona/Blaxel tunnels serve browserd at `/`, so a cached
  * controller-only session can host-fetch JSON. OpenSandbox's lifecycle proxy
@@ -80,3 +82,35 @@ export function isRetryableControllerTransport(error: unknown): boolean {
     (error instanceof BrowserControlRequestError && error.retryable)
   );
 }
+
+/** A stopped sidecar needs provisioning on its original, fenced placement.
+ * Only reads and journaled actions may recover, once across provider retries.
+ * Revalidate controller authority before starting the sidecar. */
+export async function withControllerTransportRecovery<T>(options: {
+  channelOperation: ChannelAOperation;
+  placementKind: InteractionPlacement["kind"];
+  recoveryState: { attempted: boolean };
+  transportAlreadyFailed: boolean;
+  use: () => Promise<T>;
+  admitRecovery: () => Promise<void>;
+  recover: () => Promise<T>;
+}): Promise<T> {
+  if (
+    (options.channelOperation !== "browser.read" &&
+      options.channelOperation !== "browser.action") ||
+    options.placementKind !== "sandbox_group" ||
+    options.recoveryState.attempted
+  ) {
+    return await options.use();
+  }
+  if (!options.transportAlreadyFailed) {
+    try {
+      return await options.use();
+    } catch (error) {
+      if (!isRetryableControllerTransport(error)) throw error;
+    }
+  }
+  options.recoveryState.attempted = true;
+  await options.admitRecovery();
+  return await options.recover();
+}

package/src/credit-promotion-snapshot.ts

@@ -0,0 +1,36 @@
+import { PromotionalCreditScope } from "@opengeni/contracts";
+
+const prefix = "opengeni_credit_scope_";
+const countKey = `${prefix}v1`;
+
+/** Preserve scoped status and fallback eligibility; runtime policy can update coverage.
+ * Stripe metadata values are limited to 500 characters. Keep each chunk below that. */
+export function creditScopeMetadata(scope?: PromotionalCreditScope): Record<string, string> {
+  if (!scope) return {};
+  const encoded = JSON.stringify(PromotionalCreditScope.parse(scope));
+  const chunks = encoded.match(/[\s\S]{1,400}/g)!;
+  if (chunks.length > 24)
+    throw new Error("Promotional credit policy exceeds checkout metadata limits");
+  return Object.fromEntries([
+    [countKey, String(chunks.length)],
+    ...chunks.map((chunk, index) => [`${prefix}${index}`, chunk]),
+  ]);
+}
+
+/** Missing metadata is a legacy checkout; incomplete metadata must never become unrestricted. */
+export function creditScopeFromMetadata(
+  metadata: Record<string, string> | null | undefined,
+): PromotionalCreditScope | undefined {
+  if (!metadata || !Object.keys(metadata).some((key) => key.startsWith(prefix))) return undefined;
+  const count = Number(metadata[countKey]);
+  if (!Number.isInteger(count) || count < 1 || count > 24) {
+    throw new Error("Invalid promotional credit snapshot");
+  }
+  let encoded = "";
+  for (let index = 0; index < count; index++) {
+    const chunk = metadata[`${prefix}${index}`];
+    if (!chunk) throw new Error("Incomplete promotional credit snapshot");
+    encoded += chunk;
+  }
+  return PromotionalCreditScope.parse(JSON.parse(encoded));
+}

package/src/editable-artifact-production.ts

@@ -6,6 +6,7 @@ import {
 import {
   EditableArtifactDurableExportService,
   EditableArtifactAgentApplication,
+  EDITABLE_ARTIFACT_EXPORT_FORMATS,
   EDITABLE_ARTIFACT_EXPORT_MAX_DOWNLOAD_BYTES,
   EditableArtifactCompactionPipeline,
   EditableArtifactGenesisPipeline,
@@ -47,6 +48,7 @@ import {
   PostgresEditableArtifactStore,
   listEditableArtifactIdsForSession,
   touchEditableArtifactSessionLink,
+  recordNativeDocumentInspection,
   dbSql,
   withRlsContext,
   type Database,
@@ -167,6 +169,11 @@ export async function createStandaloneEditableArtifactApplication(input: {
         await touchEditableArtifactSessionLink(input.db, scope, sessionId, artifactId),
     } satisfies EditableArtifactAgentAssociationPort),
     inspector: kernel,
+    recordInspection: async (inspection) => {
+      if (inspection.actor.kind !== "agent")
+        throw new Error("Inspection proof requires an agent attempt");
+      return recordNativeDocumentInspection(input.db, { ...inspection, actor: inspection.actor });
+    },
     officeImports,
     workspaceFiles: new EditableArtifactWorkspaceFileAdapter({
       db: input.db,
@@ -353,10 +360,13 @@ function materializationProfiles(
   }
   const codecVersion = capabilities.codecVersions["opengeni.xlsx"];
   return Object.freeze({
+    supportedFormats: EDITABLE_ARTIFACT_EXPORT_FORMATS,
     async resolve(input: Parameters<EditableArtifactMaterializationProfilePort["resolve"]>[0]) {
+      // EDITABLE_ARTIFACT_EXPORT_FORMATS is what agents are told exists.
       if (
         input.modality !== "spreadsheet" ||
         input.format !== "xlsx" ||
+        !EDITABLE_ARTIFACT_EXPORT_FORMATS[input.modality].includes(input.format) ||
         Object.keys(input.options).length !== 0
       ) {
         return null;

package/src/editable-artifact-source-session.ts

@@ -0,0 +1,123 @@
+import {
+  hasPermission,
+  requireExternalContinuationAuthority,
+  requireSessionAuthorization,
+  type ApiRouteDeps,
+  type OpenEditableArtifactLiveInput,
+} from "@opengeni/core";
+import {
+  findActiveWorkspaceApiKeyById,
+  getSession,
+  getWorkspaceGrant,
+  hasEditableArtifactSessionLink,
+  lockExternalWorkspaceMembershipLifecycle,
+  withRlsContext,
+} from "@opengeni/db";
+import { withAccessGrantSessionRlsContext } from "./access-grant-rls";
+import { sql } from "drizzle-orm";
+
+/** Supplied by the API adapter, so mounted hosts use their canonical live port. */
+export function editableArtifactSourceSessionAuthorizer(
+  deps: ApiRouteDeps,
+): NonNullable<OpenEditableArtifactLiveInput["authorizeSourceSession"]> {
+  return async (ticket, permission, transaction, signal) => {
+    signal?.throwIfAborted();
+    const authority = ticket.sourceSessionAuthority;
+    if (!authority) return true;
+    const { grant } = authority;
+    const required = permission === "edit" ? "artifacts:publish" : "artifacts:read";
+    if (
+      !hasPermission(grant.permissions, required) ||
+      !hasPermission(grant.permissions, "sessions:read")
+    ) {
+      return false;
+    }
+    // An external audit shape without the verified continuation is not authority.
+    if (grant.metadata?.externalActor && !authority.externalContinuation) return false;
+    try {
+      const scopedDeps = transaction ? { ...deps, db: transaction } : deps;
+      // Source-bound stores invoke us before their tenancy/aggregate locks.
+      // Match lifecycle writers' organization -> tenancy -> session prefix.
+      if (transaction) {
+        await lockExternalWorkspaceMembershipLifecycle(transaction, ticket.scope.accountId);
+        signal?.throwIfAborted();
+        // Tenancy writers acquire this fence before source session rows.
+        await transaction.execute(sql`select pg_advisory_xact_lock_shared(
+          hashtextextended(${`session-tenancy:${ticket.scope.workspaceId}`}, 0))`);
+        signal?.throwIfAborted();
+      }
+      return await withAccessGrantSessionRlsContext(scopedDeps, grant, async () => {
+        return await withRlsContext(scopedDeps.db, ticket.scope, async (tx) => {
+          if (authority.externalContinuation) {
+            await requireExternalContinuationAuthority(
+              tx,
+              authority.externalContinuation,
+              { ...ticket.scope, subjectId: grant.subjectId },
+              ["sessions:read", required],
+            );
+            signal?.throwIfAborted();
+          } else if (transaction) {
+            // The authenticated ticket grant is a ceiling, not proof that
+            // source-read permission still exists at the commit boundary.
+            const actor = ticket.actor;
+            if (
+              actor.kind === "human" ||
+              (actor.kind === "service" && actor.service === "configured_key")
+            ) {
+              await tx.execute(sql`select subject_id from workspace_memberships
+                where account_id = ${ticket.scope.accountId}::uuid
+                  and workspace_id = ${ticket.scope.workspaceId}::uuid
+                  and subject_id = ${grant.subjectId} for share`);
+              const live = await getWorkspaceGrant(tx, grant.subjectId, ticket.scope.workspaceId);
+              if (!live || !hasPermission(live.permissions, "sessions:read")) return false;
+            } else if (actor.kind === "service" && actor.service === "api_key") {
+              await tx.execute(sql`select id from api_keys
+                where account_id = ${ticket.scope.accountId}::uuid
+                  and id::text = ${grant.subjectId.slice("api_key:".length)}
+                for share`);
+              const live = await findActiveWorkspaceApiKeyById(tx, {
+                ...ticket.scope,
+                apiKeyId: grant.subjectId.slice("api_key:".length),
+              });
+              if (!live || !hasPermission(live.permissions, "sessions:read")) return false;
+            } else if (actor.kind === "agent") {
+              const live = await getSession(tx, ticket.scope.workspaceId, actor.sessionId);
+              if (
+                !live ||
+                (live.firstPartyMcpPermissions !== null &&
+                  !hasPermission(live.firstPartyMcpPermissions, "sessions:read"))
+              ) {
+                return false;
+              }
+            } else {
+              return false;
+            }
+            signal?.throwIfAborted();
+          }
+          // Locks protect visibility and removal of the exact association
+          // until the enclosing mutation transaction commits.
+          const linked = await hasEditableArtifactSessionLink(
+            tx,
+            ticket.scope,
+            authority.sessionId,
+            ticket.artifactId,
+            { lockForCommit: transaction !== undefined },
+          );
+          signal?.throwIfAborted();
+          if (!linked) return false;
+          await requireSessionAuthorization({ ...scopedDeps, db: tx }, grant, {
+            sessionId: authority.sessionId,
+            operation: "session.read",
+            surface: "http",
+          });
+          signal?.throwIfAborted();
+          return true;
+        });
+      });
+    } catch {
+      // Denial or an unavailable authority must stop data/writes, never fall
+      // back to artifact-only scope. The live loop closes denied readers.
+      return false;
+    }
+  };
+}

package/src/editable-artifact-websocket.ts

@@ -8,6 +8,7 @@ import {
   type EditableArtifactLiveServerFrame,
   type EditableArtifactLiveSession,
   type EditableArtifactLiveSinkPort,
+  type OpenEditableArtifactLiveInput,
 } from "@opengeni/core";
 import type {
   ApiWebSocketConnection,
@@ -35,7 +36,10 @@ export type EditableArtifactWebSocketHandler = Readonly<{
 export class EditableArtifactWebSocketTransport {
   readonly websocket: EditableArtifactWebSocketHandler;
 
-  constructor(private readonly application: EditableArtifactApplicationPort | undefined) {
+  constructor(
+    private readonly application: EditableArtifactApplicationPort | undefined,
+    private readonly authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"],
+  ) {
     this.websocket = Object.freeze({
       open: (socket) => socket.data.attach(socket),
       message: (socket, message) => socket.data.receive(message),
@@ -60,7 +64,10 @@ export class EditableArtifactWebSocketTransport {
     if (!offeredProtocol(request.headers.get("sec-websocket-protocol"))) {
       return new Response("WebSocket protocol required", { status: 426 });
     }
-    const connection = new EditableArtifactWebSocketConnection(this.application);
+    const connection = new EditableArtifactWebSocketConnection(
+      this.application,
+      this.authorizeSourceSession,
+    );
     const upgraded = server.upgrade(request, {
       data: connection,
       headers: {
@@ -82,7 +89,10 @@ export class EditableArtifactWebSocketConnection
   private queuedBytes = 0;
   private terminal = false;
 
-  constructor(private readonly application: EditableArtifactApplicationPort) {}
+  constructor(
+    private readonly application: EditableArtifactApplicationPort,
+    private readonly authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"],
+  ) {}
 
   attach(socket: EditableArtifactWebSocketLike): void {
     if (this.socket || this.terminal) {
@@ -177,6 +187,9 @@ export class EditableArtifactWebSocketConnection
         protocolVersion: frame.protocolVersion,
         resume: frame.resume,
         sink: this,
+        ...(this.authorizeSourceSession
+          ? { authorizeSourceSession: this.authorizeSourceSession }
+          : {}),
       });
       if (this.terminal) {
         await session.close("transport_error");

package/src/fatal-process-boundary.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { isDatabaseConnectionLoss } from "@opengeni/db";
 import type { Attributes, Observability, Span } from "@opengeni/observability";
 
 export type ApiFatalEvent = "startup_failure" | "unhandled_rejection" | "uncaught_exception";
@@ -15,7 +16,8 @@ export type ApiFatalReasonKind =
   | "symbol"
   | "undefined";
 
-type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan">;
+type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan"> &
+  Partial<Pick<Observability, "recordFailureDiagnostic" | "warn" | "incrementCounter">>;
 
 type ApiFatalProcess = {
   on: (
@@ -35,6 +37,14 @@ export type ApiFatalProcessBoundaryOptions = {
   flushTimeoutMs?: number;
   correlationId?: () => string;
   fallbackLog?: (message: string) => void;
+  /**
+   * Classifies an unhandled rejection that leaves no process state behind and
+   * is therefore survivable once the API is serving. Defaults to a lost
+   * database connection (deploy drain, failover, restart): the rejected query
+   * held only a pooled connection the driver has already discarded, and every
+   * durable loop retries its claim on the next tick.
+   */
+  isRecoverableRejection?: (reason: unknown) => boolean;
 };
 
 export type ApiFatalProcessBoundary = {
@@ -60,19 +70,72 @@ export function installApiFatalProcessBoundary(
   const flushTimeoutMs = options.flushTimeoutMs ?? API_FATAL_FLUSH_TIMEOUT_MS;
   const correlationId = options.correlationId ?? (() => `api-fatal.${randomUUID()}`);
   const fallbackLog = options.fallbackLog ?? ((message: string) => console.error(message));
+  const isRecoverableRejection = options.isRecoverableRejection ?? isDatabaseConnectionLoss;
   let observability = options.observability;
   let phase: ApiFatalPhase = "startup";
   let reporting = false;
 
+  const recover = (reason: unknown): boolean => {
+    if (phase !== "running" || reporting) return false;
+    let recoverable = false;
+    try {
+      recoverable = isRecoverableRejection(reason);
+    } catch {
+      return false;
+    }
+    if (!recoverable) return false;
+    const attributes = {
+      errorClass: "ApiRecoveredRejection",
+      errorCode: "api_unhandled_database_connection_loss",
+      origin: "api",
+      reasonKind: apiFatalReasonKind(reason),
+    };
+    try {
+      if (observability?.warn) {
+        observability.warn(
+          "Opengeni API recovered an unhandled database connection loss",
+          attributes,
+        );
+      } else {
+        safeFallbackLog(
+          fallbackLog,
+          "Opengeni API recovered an unhandled database connection loss (api_unhandled_database_connection_loss)",
+        );
+      }
+      observability?.incrementCounter?.({
+        name: "opengeni_api_recovered_rejections_total",
+        help: "Unhandled rejections the API survived because they only reported a lost database connection.",
+        labels: { code: "api_unhandled_database_connection_loss" },
+      });
+    } catch {
+      // Recovery never depends on the observer.
+    }
+    return true;
+  };
+
   const report = async (event: ApiFatalEvent, reason: unknown): Promise<void> => {
     if (reporting) return;
     reporting = true;
 
     const diagnostic = apiFatalDiagnostic(event, phase, reason, correlationId);
-    const message = apiFatalMessage(diagnostic);
+    let message = apiFatalMessage(diagnostic);
     const activeObservability = observability;
     try {
       if (activeObservability) {
+        try {
+          const diagnosticId = activeObservability.recordFailureDiagnostic?.({
+            code: FATAL_ERROR_CODES[event],
+            stage: phase,
+            retryDecision: "not_retryable",
+            error: reason,
+          });
+          if (diagnosticId) {
+            diagnostic.correlationId = diagnosticId;
+            message = apiFatalMessage(diagnostic);
+          }
+        } catch {
+          // Never replace the required fatal exit with an observer failure.
+        }
         let logged = false;
         try {
           activeObservability.error(message, diagnostic);
@@ -99,6 +162,7 @@ export function installApiFatalProcessBoundary(
   };
 
   const onUnhandledRejection = (reason: unknown): void => {
+    if (recover(reason)) return;
     void report("unhandled_rejection", reason);
   };
   const onUncaughtException = (reason: unknown): void => {
@@ -169,7 +233,7 @@ function apiFatalReasonKind(reason: unknown): ApiFatalReasonKind {
 
 function apiFatalMessage(diagnostic: ReturnType<typeof apiFatalDiagnostic>): string {
   return (
-    `OpenGeni API fatal process failure (${diagnostic.errorCode}; ` +
+    `Opengeni API fatal process failure (${diagnostic.errorCode}; ` +
     `phase=${diagnostic.phase}; reason_kind=${diagnostic.reasonKind}; ` +
     `correlation_id=${diagnostic.correlationId})`
   );

package/src/gateway-realtime.ts

@@ -62,7 +62,7 @@ export async function createGatewayRealtimeConnectionSecret(input: {
     throw new GatewayRealtimeBrokerError(
       "credential_unavailable",
       resolved.source === "managed"
-        ? "OpenGeni Gateway voice is not configured"
+        ? "Opengeni Gateway voice is not configured"
         : "The workspace AI Gateway connection is unavailable",
     );
   }
@@ -72,6 +72,7 @@ export async function createGatewayRealtimeConnectionSecret(input: {
     getSessionRealtimeContinuityEntries(input.db, input.workspaceId, input.sessionId),
     mintGatewayClientSecret({
       apiKey,
+      source: resolved.source,
       upstreamModelId: resolved.upstreamModelId,
       fetchImpl: input.fetchImpl ?? fetch,
     }),
@@ -86,6 +87,7 @@ export async function createGatewayRealtimeConnectionSecret(input: {
 
 async function mintGatewayClientSecret(input: {
   apiKey: string;
+  source: "managed" | "workspace";
   upstreamModelId: string;
   fetchImpl: typeof fetch;
 }): Promise<{ token: string; url: string; expiresAt: number | null }> {
@@ -105,17 +107,19 @@ async function mintGatewayClientSecret(input: {
   } catch {
     throw new GatewayRealtimeBrokerError(
       "provider_error",
-      "AI Gateway realtime token request failed",
+      "The voice provider could not be reached. Try again.",
     );
   }
   if (!response.ok) {
+    const rejected = response.status === 401 || response.status === 403;
+    // User-facing: say what to do, never which deployment credential failed.
     throw new GatewayRealtimeBrokerError(
-      response.status === 401 || response.status === 403
-        ? "credential_unavailable"
-        : "provider_error",
-      response.status === 401 || response.status === 403
-        ? "AI Gateway credentials were rejected"
-        : "AI Gateway realtime token request failed",
+      rejected ? "credential_unavailable" : "provider_error",
+      rejected
+        ? input.source === "managed"
+          ? "Opengeni voice is temporarily unavailable. Try another voice model."
+          : "Your AI Gateway key was rejected. Update it in workspace settings."
+        : "The voice provider could not start a call. Try again.",
       response.status,
     );
   }