fix(cloud-agent-next): control-plane recovery follow-ups

.specs/cloud-agent-session.md

@@ -69,15 +69,19 @@ repository.
    commands.
 3. Preparation that only acquired and booted an environment -- warm reuse, no
    real provisioning -- MUST NOT leave a completed preparation row.
-4. Running and failed preparation MUST always be visible. Failed preparation
-   MUST show an error and a way to open details.
+4. Running and failed preparation MUST always be visible. Failed preparation,
+   its triggering failed message, and its safe error MUST remain visible, with
+   a way to open details.
 5. Setup commands MUST run on the first prepare and again on every rebuild. A
    failing or timed-out setup command MUST fail preparation and the turn.
 6. Follow-up turns MUST NOT show preparation unless the environment was
    rebuilt.
 7. Preparation output MUST NOT reveal tokens or secret values.
-8. The composer MUST stay disabled until the environment is ready, and MUST say
-   which state it is waiting on.
+8. The composer MUST stay disabled while preparation or finalization runs, and
+   MUST say which state it is waiting on. After preparation failure settles the
+   turn, the composer MUST be restored when the session is writable and its
+   transport permits sending. A later submission MUST use fresh message and
+   preparation-attempt identities.
 
 ### Turn
 

packages/cloud-agent-sdk/src/base-connection.ts

@@ -57,6 +57,7 @@ export type Connection = {
   disconnect: () => void;
   reconnectWithRefreshedAuth?: () => void;
   retryReconnect: () => void;
+  recoverAfterSuccessfulMutation: () => void;
   destroy: () => void;
 };
 
@@ -80,13 +81,16 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
   let authRefreshAttempted = false;
   let connected = false;
   let reconnectAttempt = 0;
-  let exhausted = false;
+  let exhaustionReason: 'retry-limit' | 'auth-failure' | null = null;
   let generation = 0;
   let hasConnectedOnce = false;
   let stalenessTimeoutId: ReturnType<typeof setTimeout> | null = null;
   let lastMessageTime = 0;
   let hiddenAt = 0;
   let preconnectAuthRefreshAttempted = false;
+  // Coalesce successful mutations into one retry budget at a time. A later mutation may
+  // request another bounded cycle after that budget exhausts without any inbound event.
+  let mutationRecovery: 'idle' | 'pending' | 'active' = 'idle';
   const stalenessTimeoutMs = config.stalenessTimeoutMs ?? DEFAULT_STALENESS_TIMEOUT_MS;
   const maxReconnectAttempts = config.maxReconnectAttempts ?? MAX_RECONNECT_ATTEMPTS;
 
@@ -109,8 +113,8 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
   }
 
   function clearExhausted(): void {
-    if (exhausted) {
-      exhausted = false;
+    if (exhaustionReason !== null) {
+      exhaustionReason = null;
       config.onReconnectExhaustionChange?.(false);
     }
   }
@@ -178,8 +182,14 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
     if (destroyed || intentionalDisconnect || expectedGeneration !== generation) return;
 
     if (attempt >= maxReconnectAttempts) {
-      if (!exhausted) {
-        exhausted = true;
+      if (mutationRecovery === 'pending') {
+        mutationRecovery = 'active';
+        retryReconnect();
+        return;
+      }
+      mutationRecovery = 'idle';
+      if (exhaustionReason === null) {
+        exhaustionReason = 'retry-limit';
         config.onReconnectExhaustionChange?.(true);
       }
       return;
@@ -262,6 +272,7 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
       // Reset auth refresh flag on successful message
       authRefreshAttempted = false;
       reconnectAttempt = 0;
+      mutationRecovery = 'idle';
       clearExhausted();
 
       if (!connected) {
@@ -313,9 +324,10 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
       // Already tried refreshing auth and still failing - stop retrying.
       // The current physical route is gone even though no new socket follows.
       if (isAuthFailure && authRefreshAttempted) {
+        mutationRecovery = 'idle';
         notifyReplacingConnection(expectedGeneration);
-        if (!exhausted) {
-          exhausted = true;
+        if (exhaustionReason === null) {
+          exhaustionReason = 'auth-failure';
           config.onReconnectExhaustionChange?.(true);
         }
         return;
@@ -457,6 +469,7 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
     destroyed = false;
     authRefreshAttempted = false;
     preconnectAuthRefreshAttempted = false;
+    mutationRecovery = 'idle';
     connected = false;
     reconnectAttempt = 0;
     clearExhausted();
@@ -473,6 +486,7 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
     intentionalDisconnect = true;
     generation += 1;
     preconnectAuthRefreshAttempted = false;
+    mutationRecovery = 'idle';
 
     clearReconnectTimer();
     clearStalenessTimeout();
@@ -519,10 +533,28 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
     void refreshAndConnect(generation);
   }
 
+  function recoverAfterSuccessfulMutation() {
+    if (
+      destroyed ||
+      intentionalDisconnect ||
+      connected ||
+      exhaustionReason === 'auth-failure' ||
+      mutationRecovery !== 'idle'
+    )
+      return;
+    if (exhaustionReason === 'retry-limit') {
+      mutationRecovery = 'active';
+      retryReconnect();
+      return;
+    }
+    mutationRecovery = 'pending';
+  }
+
   function destroy() {
     destroyed = true;
     generation += 1;
     preconnectAuthRefreshAttempted = false;
+    mutationRecovery = 'idle';
 
     clearReconnectTimer();
     clearStalenessTimeout();
@@ -537,7 +569,14 @@ export function createBaseConnection<T>(config: BaseConnectionConfig<T>): Connec
     connected = false;
   }
 
-  return { connect, disconnect, reconnectWithRefreshedAuth, retryReconnect, destroy };
+  return {
+    connect,
+    disconnect,
+    reconnectWithRefreshedAuth,
+    retryReconnect,
+    recoverAfterSuccessfulMutation,
+    destroy,
+  };
 }
 
 export function createBrowserLifecycleHooks(): ConnectionLifecycleHooks {