@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/connection-ownership.ts

@@ -0,0 +1,180 @@
+import type { ConnectionOwnership } from "@opengeni/contracts";
+import type { AccessGrantAuthorization } from "@opengeni/core";
+import { HTTPException } from "hono/http-exception";
+
+/**
+ * Who may own a *personal* Connection.
+ *
+ * Connection setup defaults to a workspace-owned Connection; personal ownership
+ * is the explicit "Connect only for me" choice (AGENTS.md, "Connection
+ * ownership and executable personal authority are separate from turn
+ * initiation"). Only a managed human can own one, for two independent reasons:
+ * personal authority executes only through the immutable delegation snapshot
+ * frozen on a *human's* causal turn or scheduled task, and
+ * `bind_connection_authority` (migration 0256) can mint the `user` authority
+ * scope only for a subject holding an active organization membership. A
+ * machine-owned personal row therefore lands on the `legacy_user` compatibility
+ * lane and can never become a real organization-scoped authority.
+ *
+ * `principalKind` is the trusted, allow-listed signal: exactly `human_session`
+ * passes and every other value - including absent/unknown provenance - fails
+ * closed. The delegated-token contract forbids a `human_session` claim from
+ * carrying `serviceInitiator` or exact agent-attempt authority, so the claim
+ * cannot be combined with machine authority.
+ */
+
+/**
+ * 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
+ * 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
+ * `user:`/`dev` would break those hosts and would itself be the prefix-based
+ * kind inference the embedding contract forbids.
+ *
+ * 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.
+ *
+ * `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
+ * namespace being *removed* from this constant, and it documents the known
+ * machine subjects, but it is a hand-maintained list on both sides, so it
+ * cannot fail when a genuinely new machine namespace is introduced elsewhere in
+ * the repo. Adding one here is a manual step. That residual gap is acceptable
+ * only because this check is not the deciding signal anywhere: a new machine
+ * namespace still arrives with a non-`human_session` `principalKind` and is
+ * refused on that basis.
+ *
+ * It is also no longer the sole signal on any OAuth callback: a callback that
+ * persists a personal owner requires the HMAC-signed `personalOwnerVerified`
+ * state claim minted by a start path that saw the live principal.
+ */
+const RESERVED_MACHINE_SUBJECT_NAMESPACES = [
+  // packages/core/src/access/index.ts
+  "api_key",
+  "configured",
+  // packages/runtime/src/index.ts (signFirstPartyDelegatedBearer default)
+  "worker",
+  // packages/runtime/src/sandbox/codemode-authority.ts
+  "sandbox",
+  // apps/worker/src/activities/scheduled-tasks.ts
+  "scheduled_task",
+  // packages/db/src/session-queue-commands.ts
+  "attempt",
+  // Service principals (e.g. governed-learning activation).
+  "service",
+] as const;
+
+/** True only for an exact authenticated managed human. Unknown provenance fails closed. */
+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.
+    access.contextIntegrity &&
+    access.authenticatedSubjectId === grant.subjectId &&
+    grant.principalKind === "human_session" &&
+    !grant.serviceInitiator &&
+    !grant.serviceInitiatorContext &&
+    isPersonalConnectionOwnerSubject(grant.subjectId)
+  );
+}
+
+/** 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) {
+    return true;
+  }
+  const namespace = subjectId.slice(0, separator);
+  return !RESERVED_MACHINE_SUBJECT_NAMESPACES.some((reserved) => reserved === namespace);
+}
+
+export const PERSONAL_CONNECTION_PRINCIPAL_MESSAGE =
+  "personal Connection ownership requires an authenticated human; API keys, configured keys, " +
+  "services, and agent attempts can create only workspace-owned Connections";
+
+/** Personal-only connectors cannot degrade to workspace ownership, so they say so exactly. */
+export function personalOnlyConnectionPrincipalMessage(label: string): string {
+  return (
+    `${label} connects only as a personal Connection, which requires an authenticated human; ` +
+    "API keys, configured keys, services, and agent attempts cannot own one"
+  );
+}
+
+/**
+ * Rejects a non-human principal before a personal Connection is created.
+ * `label` names a personal-only connector, whose message must not suggest a
+ * workspace-owned alternative that its provider profile forbids.
+ *
+ * This shares that helper's core caller-integrity checks, then additionally
+ * 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.
+ */
+export function assertPersonalConnectionOwnerPrincipal(
+  access: AccessGrantAuthorization,
+  label?: string,
+): void {
+  if (isPersonalConnectionOwnerPrincipal(access)) {
+    return;
+  }
+  throw new HTTPException(422, {
+    message: label
+      ? personalOnlyConnectionPrincipalMessage(label)
+      : PERSONAL_CONNECTION_PRINCIPAL_MESSAGE,
+  });
+}
+
+/** The same fence expressed for a flow that resolves ownership after admission. */
+export function assertConnectionOwnershipAllowedForPrincipal(
+  ownership: ConnectionOwnership,
+  personalOwnershipAllowed: boolean,
+): void {
+  if (ownership === "personal" && !personalOwnershipAllowed) {
+    throw new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
+  }
+}
+
+/**
+ * The claim a start path mints into its HMAC-signed OAuth state when it has
+ * verified the live principal may own a personal Connection.
+ *
+ * An OAuth callback carries signed state, not a live principal, so it cannot
+ * re-evaluate `principalKind`. Requiring this claim makes the callback enforce
+ * exactly what the start path decided with the full signal, instead of guessing
+ * from the subject's shape. A state minted before this claim existed simply
+ * lacks it and fails closed for personal ownership - which is precisely the
+ * in-flight rolling-deploy window these fences exist to close.
+ */
+export const PERSONAL_OWNER_VERIFIED_STATE_CLAIM = "personalOwnerVerified" as const;
+
+/** True only for an explicit boolean `true` claim; absent or malformed fails closed. */
+export function personalOwnerVerifiedInState(payload: Record<string, unknown>): boolean {
+  return payload[PERSONAL_OWNER_VERIFIED_STATE_CLAIM] === true;
+}
+
+/**
+ * Callback-side fence for every path that persists a personal owner. Requires
+ * both the signed start-time verification and a non-machine subject.
+ */
+export function personalOwnerStateAccepted(state: {
+  ownership: ConnectionOwnership;
+  subjectId: string;
+  personalOwnerVerified: boolean;
+}): boolean {
+  if (state.ownership !== "personal") {
+    return true;
+  }
+  return state.personalOwnerVerified && isPersonalConnectionOwnerSubject(state.subjectId);
+}

package/src/controller-data-plane.ts

@@ -1,8 +1,55 @@
 import {
   BrowserControlRequestError,
   BrowserControlTransportError,
+  exposedPortAllowsHostFetch,
+  exposedPortEndpointFromUrl,
+  parseOpenSandboxSignedUriPath,
+  signedEndpointNeedsRefresh,
 } from "@opengeni/runtime/sandbox";
 
+/** Modal/Daytona/Blaxel tunnels serve browserd at `/`, so a cached
+ * controller-only session can host-fetch JSON. OpenSandbox's lifecycle proxy
+ * prefixes `/v1/sandboxes/<id>/proxy/<port>` and rewrites Authorization; JSON
+ * must stay on an exec-capable in-box curl session. OSEP-0011 signed URIs are
+ * Authorization-preserving and host-fetch like a native tunnel, but they are
+ * not durable cache keys. */
+export function controllerCacheAllowsHostFetch(url: string): boolean {
+  try {
+    return exposedPortAllowsHostFetch(exposedPortEndpointFromUrl(url));
+  } catch {
+    return false;
+  }
+}
+
+export function isOpenSandboxSignedControllerUrl(url: string): boolean {
+  try {
+    return parseOpenSandboxSignedUriPath(new URL(url).pathname) !== null;
+  } catch {
+    return false;
+  }
+}
+
+/** Signed Channel B URLs expire. Do not treat a lease-cached signed URI as an
+ * infinite controller endpoint. Unsigned native `/` tunnels stay cacheable. */
+export function controllerCachedUrlIsUsable(url: string, nowMs = Date.now()): boolean {
+  if (!controllerCacheAllowsHostFetch(url)) return false;
+  if (!isOpenSandboxSignedControllerUrl(url)) return true;
+  try {
+    return !signedEndpointNeedsRefresh(new URL(url).pathname, nowMs);
+  } catch {
+    return false;
+  }
+}
+
+export function shouldPersistControllerDataPlaneUrl(input: {
+  backend: string | null | undefined;
+  signedEndpoints: boolean;
+  url: string;
+}): boolean {
+  if (input.backend === "opensandbox" && input.signedEndpoints) return false;
+  return controllerCachedUrlIsUsable(input.url);
+}
+
 /** Prefer a lease-fenced controller endpoint for the idempotent create path.
  * Only a transport-class failure invalidates the cache and provisions once;
  * semantic failures belong to the caller and must never be replayed. */

package/src/editable-artifact-native-kernel.ts

@@ -17,6 +17,13 @@ import {
 } from "@opengeni/contracts/editable-artifact-causal-frontier";
 import { decodeEditableArtifactSerializedCommit } from "@opengeni/contracts/editable-artifact-serialized-commit";
 import { decodeEditableArtifactMutationIntent } from "@opengeni/contracts/editable-artifacts";
+import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION,
+  PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION,
+  SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
+  SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
+} from "@opengeni/contracts/editable-artifact-versions";
 import {
   MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES,
   causalFrontiersEqual,
@@ -39,9 +46,6 @@ import {
 } from "@opengeni/core";
 import type { BoundedObjectReadPort } from "@opengeni/storage";
 
-const MODEL_SCHEMA_VERSION = 1;
-const OPERATION_PROTOCOL_VERSION = 1;
-const CRDT_STATE_VERSION = 1;
 const SNAPSHOT_CHUNK_BYTES = 1024 * 1024;
 
 type RuntimeFacadeModule = Readonly<{
@@ -104,7 +108,7 @@ export class NativeEditableArtifactKernelAdapter
           modality: "spreadsheet" as const,
           committedTransactionBytes,
           kernelVersion: this.runtime.buildIdentity,
-          modelSchemaVersion: MODEL_SCHEMA_VERSION,
+          modelSchemaVersion: SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
         });
       }
       if (session.modality !== request.modality) {
@@ -116,7 +120,7 @@ export class NativeEditableArtifactKernelAdapter
         nativeReceiptBytes,
         resultingStateHash: editableArtifactStateHash(session.stateHash()),
         kernelVersion: this.runtime.buildIdentity,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(request.modality),
       });
     } finally {
       session.dispose();
@@ -188,7 +192,7 @@ export class NativeEditableArtifactKernelAdapter
         ),
         stateHash: editableArtifactStateHash(session.stateHash()),
         coveredHeadSequence: 0 as const,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(input.modality),
         kernelVersion: this.runtime.buildIdentity,
       };
       if (session.modality === "spreadsheet") {
@@ -196,8 +200,8 @@ export class NativeEditableArtifactKernelAdapter
           ...common,
           modality: "spreadsheet" as const,
           coveredCausalFrontier: domainFrontier(session.frontier()),
-          operationProtocolVersion: OPERATION_PROTOCOL_VERSION,
-          crdtStateVersion: CRDT_STATE_VERSION,
+          operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+          crdtStateVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
         });
       }
       return Object.freeze({
@@ -239,7 +243,7 @@ export class NativeEditableArtifactKernelAdapter
         ),
         stateHash: editableArtifactStateHash(session.stateHash()),
         coveredHeadSequence: input.state.artifact.headSequence,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(input.state.modality),
         kernelVersion: this.runtime.buildIdentity,
       } as const;
       if (session.modality === "spreadsheet") {
@@ -248,8 +252,8 @@ export class NativeEditableArtifactKernelAdapter
           ...common,
           modality: session.modality,
           coveredCausalFrontier: domainFrontier(session.frontier()),
-          operationProtocolVersion: OPERATION_PROTOCOL_VERSION,
-          crdtStateVersion: CRDT_STATE_VERSION,
+          operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+          crdtStateVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
         });
       }
       if (session.modality !== input.state.modality) throw new Error("Native modality mismatch");
@@ -310,12 +314,12 @@ export class NativeEditableArtifactKernelAdapter
           canonicalContentHash,
           coveredHeadSequence,
           stateHash,
-          modelSchemaVersion: MODEL_SCHEMA_VERSION,
+          modelSchemaVersion: SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
           kernelVersion: this.runtime.buildIdentity,
           fullCrdtStateVerified: true as const,
           coveredCausalFrontier,
-          operationProtocolVersion: OPERATION_PROTOCOL_VERSION,
-          crdtStateVersion: CRDT_STATE_VERSION,
+          operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+          crdtStateVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
           ...(replayedTarget ? { replayedTarget } : {}),
         });
       }
@@ -339,7 +343,7 @@ export class NativeEditableArtifactKernelAdapter
         canonicalContentHash,
         coveredHeadSequence,
         stateHash,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(session.modality),
         kernelVersion: this.runtime.buildIdentity,
         nativeRevision,
         ...(replayedTarget ? { replayedTarget } : {}),
@@ -350,6 +354,13 @@ export class NativeEditableArtifactKernelAdapter
   }
 }
 
+function modelSchemaVersionFor(modality: "spreadsheet" | "document" | "presentation"): 1 | 2 {
+  if (modality === "spreadsheet") return SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION;
+  return modality === "document"
+    ? DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION
+    : PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION;
+}
+
 function assertRuntime(
   candidate: unknown,
   location: ConfiguredArtifactRuntimeLocation,

package/src/editable-artifact-office-import.ts

@@ -22,6 +22,7 @@ import { getFilesForSubject } from "@opengeni/db";
 import {
   MAX_BOUNDED_OBJECT_CHUNK_BYTES,
   type BoundedImmutableObjectWritePort,
+  retryWhileMissing,
   type ObjectStorage,
 } from "@opengeni/storage";
 import type { Database } from "@opengeni/db";
@@ -200,7 +201,19 @@ async function readVerifiedWorkspaceFile(
   signal?: AbortSignal,
 ): Promise<Uint8Array> {
   throwIfAborted(signal);
-  const before = await storage.headFile(file);
+  const before = await retryWhileMissing(async () => {
+    try {
+      return await storage.headFile(file);
+    } catch (error) {
+      if (typeof storage.fileExists === "function" && !(await storage.fileExists(file))) {
+        return null;
+      }
+      throw error;
+    }
+  });
+  if (!before) {
+    throw new EditableArtifactOfficeImportError("source_changed");
+  }
   if (
     before.ContentLength !== file.sizeBytes ||
     before.ContentType !== file.contentType ||
@@ -215,14 +228,26 @@ async function readVerifiedWorkspaceFile(
   for (let start = 0; start < file.sizeBytes; start += MAX_BOUNDED_OBJECT_CHUNK_BYTES) {
     throwIfAborted(signal);
     const end = Math.min(file.sizeBytes, start + MAX_BOUNDED_OBJECT_CHUNK_BYTES) - 1;
-    const chunk = await storage.getFileRange(file, { start, end });
+    const chunk = await retryWhileMissing(async () => storage.getFileRange(file, { start, end }));
     if (!chunk || chunk.byteLength !== end - start + 1) {
       throw new EditableArtifactOfficeImportError("source_changed");
     }
     bytes.set(chunk, start);
     digest.update(chunk);
   }
-  const after = await storage.headFile(file);
+  const after = await retryWhileMissing(async () => {
+    try {
+      return await storage.headFile(file);
+    } catch (error) {
+      if (typeof storage.fileExists === "function" && !(await storage.fileExists(file))) {
+        return null;
+      }
+      throw error;
+    }
+  });
+  if (!after) {
+    throw new EditableArtifactOfficeImportError("source_changed");
+  }
   const sha256 = digest.digest("hex");
   if (
     after.ContentLength !== before.ContentLength ||

package/src/editable-artifact-production.ts

@@ -30,7 +30,6 @@ import {
   type EditableArtifactMaterializationProfilePort,
 } from "@opengeni/core/editable-artifacts";
 import {
-  EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION,
   EditableArtifactApplication,
   EditableArtifactCompatibilityError,
   EditableArtifactLiveServer,
@@ -41,6 +40,7 @@ import {
   type EditableArtifactLiveAuthorizationInvalidationPort,
   type EditableArtifactLiveCompatibilityPort,
 } from "@opengeni/core/editable-artifact-live";
+import { currentEditableArtifactCompatibility } from "@opengeni/contracts/editable-artifacts";
 import {
   PostgresEditableArtifactLiveReadStore,
   PostgresEditableArtifactLiveTicketStore,
@@ -194,10 +194,14 @@ export async function createStandaloneEditableArtifactApplication(input: {
     assertCompatible(
       request: Parameters<EditableArtifactLiveCompatibilityPort["assertCompatible"]>[0],
     ) {
+      const current = currentEditableArtifactCompatibility(request.artifact.modality);
       if (
-        request.protocolVersion !== EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION ||
-        request.modelSchemaVersion !== 1 ||
-        request.kernelVersion !== runtime.buildIdentity
+        request.modality !== request.artifact.modality ||
+        request.liveProtocolVersion !== current.liveProtocolVersion ||
+        request.modelSchemaVersion !== current.modelSchemaVersion ||
+        request.snapshotVersion !== current.snapshotVersion ||
+        request.commandProtocolVersion !== current.commandProtocolVersion ||
+        request.committedTransactionProtocolVersion !== current.committedTransactionProtocolVersion
       ) {
         throw new EditableArtifactCompatibilityError();
       }
@@ -334,14 +338,16 @@ class RandomEditableArtifactDurableExportIds implements EditableArtifactDurableE
 function materializationProfiles(
   capabilities: EditableArtifactNativeMaterializerCapabilities,
 ): EditableArtifactMaterializationProfilePort {
+  const spreadsheetCompatibility = currentEditableArtifactCompatibility("spreadsheet");
   if (
     capabilities.protocol !== "OGAMC001" ||
     capabilities.runtimeKind !== "native" ||
     capabilities.maxOutputBytes !== EDITABLE_ARTIFACT_EXPORT_MAX_DOWNLOAD_BYTES ||
     capabilities.codecVersions["opengeni.xlsx"] === undefined ||
-    !capabilities.supportedModelSchemaVersions.includes(1) ||
-    !capabilities.supportedOperationProtocolVersions.includes(1) ||
-    !capabilities.supportedSnapshotProtocolVersions.includes(1)
+    capabilities.supportedModelSchemaVersions[0] !== spreadsheetCompatibility.modelSchemaVersion ||
+    capabilities.supportedOperationProtocolVersions[0] !==
+      spreadsheetCompatibility.committedTransactionProtocolVersion ||
+    capabilities.supportedSnapshotProtocolVersions[0] !== spreadsheetCompatibility.snapshotVersion
   ) {
     throw new Error("Verified artifact materializer profile is incompatible");
   }

package/src/editable-artifact-websocket.ts

@@ -9,31 +9,22 @@ import {
   type EditableArtifactLiveSession,
   type EditableArtifactLiveSinkPort,
 } from "@opengeni/core";
+import type {
+  ApiWebSocketConnection,
+  ApiWebSocketLike,
+  ApiWebSocketUpgradeServer,
+} from "./api-websocket";
 
 export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PATH = "/v1/editable-artifacts/live";
-export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v1";
+export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v2";
 export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES = 8 * 1024 * 1024 + 64 * 1024;
 
 const MAX_QUEUED_MESSAGES = 64;
 const MAX_QUEUED_BYTES = 12 * 1024 * 1024;
 
-export type EditableArtifactWebSocketLike = Readonly<{
-  data: EditableArtifactWebSocketConnection;
-  send(data: Uint8Array, compress?: boolean): number;
-  close(code?: number, reason?: string): void;
-  readonly bufferedAmount?: number;
-  getBufferedAmount?(): number;
-}>;
+export type EditableArtifactWebSocketLike = ApiWebSocketLike;
 
-export type EditableArtifactWebSocketUpgradeServer = Readonly<{
-  upgrade(
-    request: Request,
-    options: Readonly<{
-      data: EditableArtifactWebSocketConnection;
-      headers: HeadersInit;
-    }>,
-  ): boolean;
-}>;
+export type EditableArtifactWebSocketUpgradeServer = ApiWebSocketUpgradeServer;
 
 export type EditableArtifactWebSocketHandler = Readonly<{
   open(socket: EditableArtifactWebSocketLike): void;
@@ -81,7 +72,9 @@ export class EditableArtifactWebSocketTransport {
 }
 
 /** One socket, one consumed ticket, one stream epoch. */
-export class EditableArtifactWebSocketConnection implements EditableArtifactLiveSinkPort {
+export class EditableArtifactWebSocketConnection
+  implements EditableArtifactLiveSinkPort, ApiWebSocketConnection
+{
   private socket: EditableArtifactWebSocketLike | null = null;
   private session: EditableArtifactLiveSession | null = null;
   private work: Promise<void> = Promise.resolve();

package/src/editable-artifact-workspace-files.ts

@@ -5,7 +5,7 @@ import {
   type EditableArtifactDurableExportService,
 } from "@opengeni/core/editable-artifacts";
 import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
-import type { ObjectHead, ObjectStorage } from "@opengeni/storage";
+import { retryWhileMissing, type ObjectHead, type ObjectStorage } from "@opengeni/storage";
 
 const UPLOAD_INTENT_TTL_MS = 60 * 60_000;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
@@ -81,7 +81,7 @@ export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAge
         if (existing) {
           assertStoredExport(existing, download.byteSize, download.mimeType, sha256);
         } else {
-          await storage.putObjectStreamIfAbsent({
+          const created = await storage.putObjectStreamIfAbsent({
             key: objectKey,
             contentType: download.mimeType,
             chunks: download.chunks(input.signal ? { signal: input.signal } : {}),
@@ -89,18 +89,28 @@ export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAge
             sha256,
             ...(input.signal ? { signal: input.signal } : {}),
           });
-          const stored = await storage.headObject(objectKey);
-          assertStoredExport(stored, download.byteSize, download.mimeType, sha256);
+          if (!created) {
+            await assertVisibleExport(
+              storage,
+              objectKey,
+              download.byteSize,
+              download.mimeType,
+              sha256,
+              input.signal,
+            );
+          }
         }
         await download.assertUnchanged(input.signal);
         throwIfAborted(input.signal);
         file = await this.completeFile(this.dependencies.db, input.scope.workspaceId, uploadId);
       } else {
-        assertStoredExport(
-          await storage.headObject(objectKey),
+        await assertVisibleExport(
+          storage,
+          objectKey,
           download.byteSize,
           download.mimeType,
           sha256,
+          input.signal,
         );
         await download.assertUnchanged(input.signal);
       }
@@ -133,6 +143,21 @@ export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAge
   }
 }
 
+async function assertVisibleExport(
+  storage: ObjectStorage,
+  objectKey: string,
+  byteSize: number,
+  contentType: string,
+  sha256: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const head = await retryWhileMissing(
+    async () => await storage.headObject!(objectKey),
+    signal ? { signal } : {},
+  );
+  assertStoredExport(head, byteSize, contentType, sha256);
+}
+
 function assertStoredExport(
   head: ObjectHead | null,
   byteSize: number,

package/src/http/api-error.ts

@@ -1,4 +1,5 @@
 import type { ErrorCode } from "@opengeni/contracts";
+import { WorkspaceControlBusyError } from "@opengeni/db";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { HTTPException } from "hono/http-exception";
 
@@ -6,6 +7,7 @@ type ApiHttpErrorOptions = {
   code: ErrorCode;
   message: string;
   retryable?: boolean;
+  outcomeUnknown?: boolean;
   details?: Record<string, unknown>;
 };
 
@@ -13,6 +15,7 @@ type ApiHttpErrorOptions = {
 export class ApiHttpError extends HTTPException {
   readonly code: ErrorCode;
   readonly retryable: boolean | undefined;
+  readonly outcomeUnknown: boolean | undefined;
   readonly details: Record<string, unknown> | undefined;
 
   constructor(status: number, options: ApiHttpErrorOptions) {
@@ -20,6 +23,31 @@ export class ApiHttpError extends HTTPException {
     this.name = "ApiHttpError";
     this.code = options.code;
     this.retryable = options.retryable;
+    this.outcomeUnknown = options.outcomeUnknown;
     this.details = options.details;
   }
 }
+
+/**
+ * A request-scoped session/workspace mutation could not enter the workspace
+ * control prefix within its bounded wait. The transaction rolled back before
+ * any write, so the outcome is known and the client may retry. `app.onError`
+ * applies this once for every route; Slack interactions keep the raw typed
+ * error so their retry classifier treats it as transient.
+ */
+export function workspaceControlBusyHttpError(error: unknown): ApiHttpError | null {
+  const busy =
+    error instanceof WorkspaceControlBusyError
+      ? error
+      : error instanceof HTTPException && error.cause instanceof WorkspaceControlBusyError
+        ? error.cause
+        : null;
+  if (!busy) return null;
+  return new ApiHttpError(503, {
+    code: "upstream_unavailable",
+    message: "The workspace is busy applying other session commands; retry shortly.",
+    retryable: true,
+    outcomeUnknown: false,
+    details: { code: busy.code, lockTimeoutMs: busy.lockTimeoutMs },
+  });
+}

package/src/http/auth.ts

@@ -40,6 +40,9 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (path === "/v1/webhooks/stripe") {
     return true;
   }
+  if (c.req.method === "POST" && path.startsWith("/v1/webhooks/automations/")) {
+    return true;
+  }
   if (
     path === "/v1/github/setup" ||
     path === "/v1/github/install/callback" ||
@@ -51,6 +54,7 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (
     path === "/v1/integrations/oauth/callback" ||
     path === "/v1/integrations/provider-oauth/callback" ||
+    path === "/v1/integrations/github-personal/oauth/callback" ||
     path === "/v1/integrations/google-drive/callback" ||
     path === "/v1/integrations/oauth/client-metadata.json" ||
     path === "/v1/integrations/slack/callback" ||