@turingfocus/chat-gateway-tfrobot 0.5.0 → 0.7.0

package/dist/socket.js

@@ -1,10 +1,10 @@
 import { io } from "socket.io-client";
-import { chatErrorSchema, chatUpdateSchema, createGatewayDeadlineExceededError, isGatewayDeadlineExceeded, } from "@turingfocus/chat-protocol";
+import { chatErrorSchema, chatUpdateSchema, createGatewayDeadlineExceededError, getTimelineItemKey, isGatewayDeadlineExceeded, } from "@turingfocus/chat-protocol";
 import { awaitBounded } from "./bounded.js";
 import { chatErrorEventDtoSchema, eventDtoSchema, messageDtoSchema, socketProtocolErrorDtoSchema, stateChangedDtoSchema, statusDtoSchema, } from "./dto.js";
 import { mapEventUpdate, mapMessageUpdate, mapRun, mapUnknownSocketEvent, } from "./mapper.js";
 import { sanitizeCredentialError, sanitizeCredentialRaw, sanitizeCredentialText, } from "./redaction.js";
-import { isValidTFRobotSession } from "./types.js";
+import { isValidTFRobotSession, resolveTFRobotServerProfile } from "./types.js";
 const KNOWN_EVENTS = new Set([
     "chat_error",
     "chat_event",
@@ -17,6 +17,130 @@ const KNOWN_EVENTS = new Set([
 ]);
 const MAX_TIMER_DELAY = 2_147_483_647;
 const RECONNECT_AUTH_TIMEOUT_MS = 10_000;
+const RECONNECT_JOIN_TIMEOUT_MS = 10_000;
+const parseJoinAcknowledgement = (value, reconnect, acceptEmpty) => {
+    if (value === undefined) {
+        return {
+            accepted: reconnect || acceptEmpty,
+            empty: true,
+            recoveryComplete: false,
+            ...(reconnect || acceptEmpty
+                ? {}
+                : { rejectionCode: "validation" }),
+        };
+    }
+    if (value === null) {
+        return {
+            accepted: false,
+            empty: false,
+            recoveryComplete: false,
+            rejectionCode: "validation",
+        };
+    }
+    if (value === false) {
+        return {
+            accepted: false,
+            empty: false,
+            recoveryComplete: false,
+            rejectionCode: "validation",
+        };
+    }
+    if (value === true) {
+        return { accepted: true, empty: false, recoveryComplete: !reconnect };
+    }
+    if (typeof value !== "object") {
+        return {
+            accepted: false,
+            empty: false,
+            recoveryComplete: false,
+            rejectionCode: "validation",
+        };
+    }
+    const record = value;
+    const booleanAliases = ["ok", "accepted", "success"];
+    const hasInvalidBooleanAlias = booleanAliases.some((alias) => Object.hasOwn(record, alias) && typeof record[alias] !== "boolean");
+    const statusAliases = ["status", "statusCode", "code"];
+    const hasInvalidStatusAlias = statusAliases.some((alias) => Object.hasOwn(record, alias) && record[alias] === undefined);
+    const statuses = [record["status"], record["statusCode"], record["code"]]
+        .filter((status) => status !== undefined)
+        .map((status) => {
+        const numeric = typeof status === "number"
+            ? status
+            : typeof status === "string" && /^\d{3}$/u.test(status)
+                ? Number(status)
+                : undefined;
+        const normalized = typeof status === "string" ? status.trim().toLowerCase() : undefined;
+        const accepted = (numeric !== undefined && numeric >= 200 && numeric < 300) ||
+            normalized === "ok" ||
+            normalized === "success" ||
+            normalized === "accepted" ||
+            normalized === "joined";
+        const rejected = (numeric !== undefined && numeric >= 400) ||
+            normalized === "error" ||
+            normalized === "failed" ||
+            normalized === "forbidden" ||
+            normalized === "unauthorized" ||
+            normalized === "rejected";
+        return { accepted, normalized, numeric, rejected };
+    });
+    const hasUnknownStatus = statuses.some((status) => !status.accepted && !status.rejected);
+    const explicitlyAccepted = record["ok"] === true ||
+        record["accepted"] === true ||
+        record["success"] === true ||
+        statuses.some((status) => status.accepted);
+    const cursorAliases = ["cursor", "recoveryCursor"];
+    const cursorValues = cursorAliases
+        .filter((alias) => Object.hasOwn(record, alias))
+        .map((alias) => record[alias]);
+    const cursorInvalid = cursorValues.some((cursorValue) => typeof cursorValue !== "string");
+    const cursorConflict = cursorValues.length > 1 &&
+        cursorValues.some((cursorValue) => cursorValue !== cursorValues[0]);
+    const recoveryAliases = ["recovered", "recoveryComplete"];
+    const recoveryDeclarations = recoveryAliases
+        .filter((alias) => Object.hasOwn(record, alias))
+        .map((alias) => record[alias]);
+    const recoveryInvalid = recoveryDeclarations.some((declaration) => typeof declaration !== "boolean");
+    const recoveryConflict = recoveryDeclarations.includes(true) && recoveryDeclarations.includes(false);
+    const normalizedError = typeof record["error"] === "string"
+        ? record["error"].trim().toLowerCase()
+        : undefined;
+    const explicitlyRejected = hasInvalidBooleanAlias ||
+        hasInvalidStatusAlias ||
+        record["ok"] === false ||
+        record["accepted"] === false ||
+        record["success"] === false ||
+        record["error"] !== undefined ||
+        cursorInvalid ||
+        cursorConflict ||
+        recoveryInvalid ||
+        recoveryConflict ||
+        (!reconnect && recoveryDeclarations.includes(false)) ||
+        hasUnknownStatus ||
+        statuses.some((status) => status.rejected);
+    const accepted = explicitlyAccepted && !explicitlyRejected;
+    const cursor = cursorValues[0];
+    const recoveryComplete = !reconnect ||
+        (recoveryDeclarations.length > 0 &&
+            recoveryDeclarations.every((declaration) => declaration === true));
+    const authenticationRejected = statuses.some(({ normalized, numeric }) => numeric === 401 || normalized === "unauthorized") || normalizedError === "unauthorized";
+    const authorizationRejected = statuses.some(({ normalized, numeric }) => numeric === 403 || normalized === "forbidden") || normalizedError === "forbidden";
+    return {
+        accepted,
+        empty: false,
+        ...(authenticationRejected
+            ? { rejectionCode: "authentication" }
+            : authorizationRejected
+                ? { rejectionCode: "authorization" }
+                : accepted
+                    ? {}
+                    : { rejectionCode: "validation" }),
+        recoveryComplete,
+        ...(typeof cursor === "string" ? { cursor } : {}),
+        ...(typeof record["message"] === "string"
+            ? { message: record["message"] }
+            : {}),
+    };
+};
 const sameRun = (first, second) => first === second ||
     (first != null &&
         second != null &&
@@ -101,25 +225,65 @@ export const createSocketIoFactoryWith = (connect) => ({ getAuth, namespaceUrl,
     },
 });
 export const createSocketIoFactory = createSocketIoFactoryWith(io);
+const MAX_RECOVERY_IDENTITIES = 10_000;
+const rememberBoundedSetValue = (values, value) => {
+    values.delete(value);
+    values.add(value);
+    while (values.size > MAX_RECOVERY_IDENTITIES) {
+        const oldest = values.values().next().value;
+        if (oldest === undefined)
+            break;
+        values.delete(oldest);
+    }
+};
+const rememberBoundedMapValue = (values, key, value) => {
+    values.delete(key);
+    values.set(key, value);
+    while (values.size > MAX_RECOVERY_IDENTITIES) {
+        const oldest = values.keys().next().value;
+        if (oldest === undefined)
+            break;
+        values.delete(oldest);
+    }
+};
+export const recoveryIdentityOfUpdate = (update) => {
+    if (update.kind === "timeline.upsert") {
+        return getTimelineItemKey(update.item);
+    }
+    if (update.kind === "event.transition.upsert") {
+        return `event:${update.event.id}:transition:${update.event.transition.id}`;
+    }
+    return undefined;
+};
+const recoveryIdentitiesOfSnapshot = (snapshot) => snapshot.timeline.flatMap((item) => item.kind === "agent-event"
+    ? item.transitions.map((transition) => `event:${item.id}:transition:${transition.id}`)
+    : [getTimelineItemKey(item)]);
 export class TFRobotSocketClient {
-    #active;
     #disposed = false;
-    #establishmentAbort;
+    #establishing;
+    #pendingEstablishment;
     #factory;
     #namespaceUrl;
     #now;
     #options;
     #path;
+    #profile;
+    #currentServerRestLoader;
     #reconnectStatusLoader;
+    #recoveryCheckpoints = new Map();
     #runs = new Map();
-    constructor(options, reconnectStatusLoader) {
+    #subscriptions = new Set();
+    #subscriptionGeneration = 0;
+    constructor(options, reconnectStatusLoader, currentServerRestLoader) {
         this.#options = options;
         this.#factory = options.socketFactory ?? createSocketIoFactory;
         this.#path = options.socketPath ?? "/socket.io";
         this.#now = options.now ?? Date.now;
+        this.#profile = resolveTFRobotServerProfile(options.serverProfile);
         this.#namespaceUrl =
             options.socketNamespaceUrl ?? this.#defaultNamespaceUrl(options.baseUrl);
         this.#reconnectStatusLoader = reconnectStatusLoader;
+        this.#currentServerRestLoader = currentServerRestLoader;
     }
     async subscribe(conversationId, options, observer) {
         if (this.#disposed) {
@@ -134,19 +298,29 @@ export class TFRobotSocketClient {
                 error: createGatewayDeadlineExceededError(),
             };
         }
-        this.#deactivateCurrent();
+        const generation = ++this.#subscriptionGeneration;
+        const subscriptionId = `tfrobot-subscription-${generation}`;
+        this.#cancelEstablishment();
         const establishmentAbort = new AbortController();
-        this.#establishmentAbort = establishmentAbort;
-        const authOutcome = await awaitBounded(() => this.#getSocketAuth(conversationId, "connect"), {
+        const pendingEstablishment = {
+            abort: establishmentAbort,
+            conversationId,
+            generation,
+        };
+        this.#pendingEstablishment = pendingEstablishment;
+        const clearPendingEstablishment = () => {
+            if (this.#pendingEstablishment === pendingEstablishment) {
+                this.#pendingEstablishment = undefined;
+            }
+        };
+        const authOutcome = await awaitBounded(() => this.#getSocketSession(conversationId, "connect"), {
             deadlineAt: options.deadlineAt,
             now: this.#now,
             signal: establishmentAbort.signal,
         });
-        if (this.#establishmentAbort === establishmentAbort) {
-            this.#establishmentAbort = undefined;
-        }
         switch (authOutcome.kind) {
             case "aborted": {
+                clearPendingEstablishment();
                 return {
                     ok: false,
                     error: this.#error("conflict", this.#disposed
@@ -155,12 +329,14 @@ export class TFRobotSocketClient {
                 };
             }
             case "deadline": {
+                clearPendingEstablishment();
                 return {
                     ok: false,
                     error: createGatewayDeadlineExceededError(),
                 };
             }
             case "error": {
+                clearPendingEstablishment();
                 return {
                     ok: false,
                     error: this.#error("authentication", "Unable to obtain a TFRobot Socket session", true, undefined),
@@ -171,14 +347,43 @@ export class TFRobotSocketClient {
             }
         }
         if (this.#disposed || establishmentAbort.signal.aborted) {
+            clearPendingEstablishment();
             return {
                 ok: false,
                 error: this.#error("conflict", "TFRobot Gateway was disposed during subscription", false, undefined),
             };
         }
-        const credentialValues = new Set(Object.values(authOutcome.value));
+        const initialSession = authOutcome.value;
+        if (this.#profile.kind === "current-server") {
+            const preflight = await this.#currentServerRestLoader({
+                checkpoint: new Set(),
+                conversationId,
+                deadlineAt: options.deadlineAt,
+                limits: {
+                    ...this.#profile.rebase,
+                    maxItems: this.#profile.rebase.pageSize,
+                    maxPages: 1,
+                },
+                session: initialSession,
+                signal: establishmentAbort.signal,
+            });
+            if (this.#disposed || establishmentAbort.signal.aborted) {
+                clearPendingEstablishment();
+                return {
+                    ok: false,
+                    error: this.#error("conflict", "TFRobot subscription was replaced during REST preflight", false, undefined),
+                };
+            }
+            if (!preflight.ok) {
+                clearPendingEstablishment();
+                return preflight;
+            }
+        }
+        const initialAuth = authOf(initialSession);
+        const credentialValues = new Set(Object.values(initialAuth));
         const errorConversationId = () => sanitizeCredentialText(conversationId, credentialValues);
-        let firstAuth = authOutcome.value;
+        let firstAuth = initialAuth;
+        let currentServerSession = initialSession;
         let authenticationFailure;
         const connectionAbort = new AbortController();
         let socket;
@@ -195,20 +400,22 @@ export class TFRobotSocketClient {
                         firstAuth = undefined;
                         return auth;
                     }
-                    const reconnectAuth = await awaitBounded(() => this.#getSocketAuth(conversationId, "reconnect"), {
+                    const reconnectSession = await awaitBounded(() => this.#getSocketSession(conversationId, "reconnect"), {
                         deadlineAt: this.#now() + RECONNECT_AUTH_TIMEOUT_MS,
                         now: this.#now,
                         signal: connectionAbort.signal,
                     });
-                    if (reconnectAuth.kind === "value") {
-                        for (const value of Object.values(reconnectAuth.value)) {
+                    if (reconnectSession.kind === "value") {
+                        currentServerSession = reconnectSession.value;
+                        const reconnectAuth = authOf(reconnectSession.value);
+                        for (const value of Object.values(reconnectAuth)) {
                             credentialValues.add(value);
                         }
-                        return reconnectAuth.value;
+                        return reconnectAuth;
                     }
-                    const reason = reconnectAuth.kind === "error"
-                        ? reconnectAuth.reason
-                        : new Error(reconnectAuth.kind === "deadline"
+                    const reason = reconnectSession.kind === "error"
+                        ? reconnectSession.reason
+                        : new Error(reconnectSession.kind === "deadline"
                             ? "TFRobot Socket session refresh exceeded its deadline"
                             : "TFRobot Socket session refresh was cancelled");
                     authenticationFailure = reason;
@@ -218,12 +425,27 @@ export class TFRobotSocketClient {
         }
         catch (reason) {
             connectionAbort.abort();
+            clearPendingEstablishment();
             return {
                 ok: false,
                 error: this.#transportError(reason, "Unable to create the TFRobot Socket transport", conversationId, credentialValues),
             };
         }
         const listeners = new Map();
+        let joinTimeout;
+        const activeErrorIds = new Map();
+        const replaceableErrorSources = new Set([
+            "authentication",
+            "connection",
+            "recovery",
+            "subscription",
+        ]);
+        let errorSequence = 0;
+        let publishUpdate = () => undefined;
+        const pendingNotifications = [];
+        const pendingRealtimeActions = [];
+        let joinPending = false;
+        let subscriptionEstablished = false;
         let setupFailure;
         const add = (eventName, listener) => {
             if (setupFailure !== undefined)
@@ -244,15 +466,52 @@ export class TFRobotSocketClient {
                 // Diagnostics are observational and cannot break the chat stream.
             }
         };
-        const report = (error) => {
-            if (!active.active)
-                return;
+        const notifyError = (error) => {
             try {
                 observer.error?.(error);
             }
             catch {
                 // Host observers are isolated from the transport listener.
             }
+        };
+        const resolveError = (source) => {
+            const errorId = activeErrorIds.get(source);
+            if (errorId === undefined || !active.active)
+                return;
+            activeErrorIds.delete(source);
+            publishUpdate(chatUpdateSchema.parse({
+                kind: "error.resolved",
+                conversationId: errorConversationId(),
+                errorId,
+            }));
+        };
+        const report = (error, source = "protocol") => {
+            if (!active.active)
+                return;
+            if (replaceableErrorSources.has(source))
+                resolveError(source);
+            const errorId = `${subscriptionId}:error:${++errorSequence}`;
+            if (replaceableErrorSources.has(source)) {
+                activeErrorIds.set(source, errorId);
+            }
+            const occurrenceError = error.conversationId === undefined
+                ? error
+                : { ...error, conversationId: errorConversationId() };
+            publishUpdate(chatUpdateSchema.parse({
+                kind: "error.reported",
+                conversationId: errorConversationId(),
+                error: occurrenceError,
+                errorId,
+                source,
+                scope: source === "domain"
+                    ? { kind: "conversation", id: errorConversationId() }
+                    : { kind: "subscription", id: subscriptionId },
+                generation,
+            }));
+            if (subscriptionEstablished)
+                notifyError(error);
+            else
+                pendingNotifications.push({ kind: "error", error });
             diagnose(error);
         };
         const sanitizePayload = (payload) => {
@@ -276,6 +535,10 @@ export class TFRobotSocketClient {
                 updateConversationId !== errorConversationId()) {
                 return;
             }
+            if (!subscriptionEstablished) {
+                pendingNotifications.push({ kind: "update", update });
+                return;
+            }
             try {
                 observer.next(update);
             }
@@ -283,6 +546,80 @@ export class TFRobotSocketClient {
                 diagnose(this.#error("unknown", "TFRobot Gateway observer rejected an update", false, errorConversationId()));
             }
         };
+        publishUpdate = next;
+        const dispatchRealtime = (action) => {
+            if (active.acceptingEvents)
+                action();
+            else if (joinPending)
+                pendingRealtimeActions.push(action);
+        };
+        const flushRealtime = () => {
+            for (const action of pendingRealtimeActions.splice(0))
+                action();
+        };
+        const lifecycle = (status, recovery, joinLatencyMs) => {
+            if (!active.active)
+                return;
+            const value = {
+                status,
+                generation,
+                reconnectAttempt: active.reconnectAttempt,
+                subscriptionId,
+                ...(recovery === undefined ? {} : { recovery }),
+            };
+            const update = chatUpdateSchema.parse({
+                kind: "lifecycle.changed",
+                conversationId: errorConversationId(),
+                lifecycle: value,
+            });
+            next(update);
+            try {
+                void Promise.resolve(this.#options.onLifecycleDiagnostic?.({
+                    kind: "socket.lifecycle",
+                    conversationId: errorConversationId(),
+                    subscriptionId,
+                    generation,
+                    status,
+                    reconnectAttempt: active.reconnectAttempt,
+                    ...(joinLatencyMs === undefined ? {} : { joinLatencyMs }),
+                    ...(recovery === undefined
+                        ? {}
+                        : {
+                            recoveryComplete: recovery.complete,
+                            ...(recovery.assurance === undefined
+                                ? {}
+                                : { recoveryAssurance: recovery.assurance }),
+                            ...(recovery.cursor === undefined
+                                ? {}
+                                : { recoveryCursor: recovery.cursor }),
+                            ...(recovery.reason === undefined
+                                ? {}
+                                : { recoveryReason: recovery.reason }),
+                            ...(recovery.source === undefined
+                                ? {}
+                                : { recoverySource: recovery.source }),
+                        }),
+                })).catch(() => undefined);
+            }
+            catch {
+                // Lifecycle diagnostics are observational.
+            }
+        };
+        const enterAuthRequired = () => {
+            active.acceptingEvents = false;
+            active.authRequired = true;
+            active.terminal = true;
+            joinPending = false;
+            pendingRealtimeActions.length = 0;
+            active.recoveryRevision += 1;
+            lifecycle("auth-required");
+            try {
+                active.socket.disconnect();
+            }
+            catch {
+                // Authentication is already terminal for this subscription episode.
+            }
+        };
         const mapAndNext = (invalidMessage, map) => {
             let update;
             try {
@@ -292,13 +629,87 @@ export class TFRobotSocketClient {
                 report(this.#error("validation", invalidMessage, false, errorConversationId()));
                 return;
             }
+            const recoveryIdentity = recoveryIdentityOfUpdate(update);
+            if (recoveryIdentity !== undefined) {
+                active.realtimeRevision += 1;
+                rememberBoundedMapValue(active.realtimeIdentityRevisions, recoveryIdentity, active.realtimeRevision);
+                const checkpoint = this.#recoveryCheckpoints.get(conversationId) ?? new Set();
+                rememberBoundedSetValue(checkpoint, recoveryIdentity);
+                this.#recoveryCheckpoints.set(conversationId, checkpoint);
+            }
             next(update);
         };
+        const rebaseCurrentServer = async (recoveryRevision, runRevision, session, checkpoint, realtimeRevision) => {
+            if (this.#profile.kind !== "current-server") {
+                return { kind: "failure" };
+            }
+            const result = await this.#currentServerRestLoader({
+                checkpoint,
+                conversationId,
+                deadlineAt: this.#now() + this.#profile.rebase.deadlineMs,
+                limits: this.#profile.rebase,
+                session,
+                signal: connectionAbort.signal,
+            });
+            if (!active.active ||
+                !this.#subscriptions.has(active) ||
+                !active.socket.connected ||
+                active.recoveryRevision !== recoveryRevision) {
+                return { kind: "failure" };
+            }
+            if (!result.ok) {
+                const error = sanitizeCredentialError(result.error, credentialValues);
+                if (error.code === "authentication" || error.code === "authorization") {
+                    report(error, "authentication");
+                    return { kind: "auth-required" };
+                }
+                report(error, "recovery");
+                return { kind: "failure" };
+            }
+            const remembered = this.#recoveryCheckpoints.get(conversationId) ?? new Set();
+            for (const update of result.value.updates) {
+                const identity = recoveryIdentityOfUpdate(update);
+                if (identity !== undefined &&
+                    (active.realtimeIdentityRevisions.get(identity) ?? 0) >
+                        realtimeRevision) {
+                    continue;
+                }
+                next(update);
+                if (identity !== undefined)
+                    rememberBoundedSetValue(remembered, identity);
+            }
+            this.#recoveryCheckpoints.set(conversationId, remembered);
+            if (active.runRevision === runRevision) {
+                const previous = this.#runs.get(conversationId);
+                this.#runs.set(conversationId, result.value.run);
+                if (!sameRun(previous, result.value.run)) {
+                    next(chatUpdateSchema.parse({
+                        kind: "run.replace",
+                        conversationId: errorConversationId(),
+                        run: result.value.run,
+                    }));
+                }
+            }
+            const reason = result.value.checkpointReached
+                ? "rest-rebase-reached-checkpoint"
+                : result.value.boundedBy === undefined
+                    ? "rest-rebase-history-exhausted"
+                    : `rest-rebase-${result.value.boundedBy}`;
+            return { kind: "success", reason };
+        };
         let settleEstablishment;
-        let connectedOnce = false;
         add("connect", () => {
             if (!active.active)
                 return;
+            if (active.terminal) {
+                try {
+                    active.socket.disconnect();
+                }
+                catch {
+                    // Terminal subscriptions never rejoin.
+                }
+                return;
+            }
             if (settleEstablishment !== undefined &&
                 isGatewayDeadlineExceeded(options, this.#now())) {
                 settleEstablishment({
@@ -307,13 +718,263 @@ export class TFRobotSocketClient {
                 });
                 return;
             }
-            const reconnect = connectedOnce;
-            connectedOnce = true;
+            if (joinTimeout !== undefined) {
+                clearTimeout(joinTimeout);
+                joinTimeout = undefined;
+            }
+            const reconnect = subscriptionEstablished;
+            if (reconnect)
+                active.reconnectAttempt += 1;
+            const rebaseCheckpoint = new Set(this.#recoveryCheckpoints.get(conversationId) ?? []);
+            const rebaseRealtimeRevision = active.realtimeRevision;
             const recoveryRevision = ++active.recoveryRevision;
-            try {
-                socket.emit("join_conversation", {
-                    conversation_id: conversationId,
+            const runRevision = active.runRevision;
+            const joinStartedAt = this.#now();
+            active.acceptingEvents = false;
+            joinPending = true;
+            pendingRealtimeActions.length = 0;
+            lifecycle("joining");
+            let acknowledgementSettled = false;
+            const settleJoin = (...acknowledgementArguments) => {
+                if (!active.active ||
+                    !this.#subscriptions.has(active) ||
+                    active.recoveryRevision !== recoveryRevision) {
+                    return;
+                }
+                if (acknowledgementSettled)
+                    return;
+                acknowledgementSettled = true;
+                if (joinTimeout !== undefined) {
+                    clearTimeout(joinTimeout);
+                    joinTimeout = undefined;
+                }
+                let acknowledgement;
+                try {
+                    const rawAcknowledgement = acknowledgementArguments[0];
+                    acknowledgement = parseJoinAcknowledgement(rawAcknowledgement === undefined || rawAcknowledgement === true
+                        ? rawAcknowledgement
+                        : sanitizeCredentialRaw(rawAcknowledgement, credentialValues), reconnect, this.#profile.kind === "current-server");
+                }
+                catch {
+                    acknowledgement = {
+                        accepted: false,
+                        empty: false,
+                        recoveryComplete: false,
+                        rejectionCode: "validation",
+                        message: "Invalid TFRobot conversation subscription acknowledgement",
+                    };
+                }
+                if (!acknowledgement.accepted) {
+                    joinPending = false;
+                    pendingRealtimeActions.length = 0;
+                    const rejectionCode = acknowledgement.rejectionCode ?? "validation";
+                    const error = this.#error(rejectionCode, acknowledgement.message ??
+                        "TFRobot conversation subscription was rejected", false, errorConversationId());
+                    if (settleEstablishment !== undefined) {
+                        lifecycle("subscription-failed");
+                        if (rejectionCode === "authentication" ||
+                            rejectionCode === "authorization") {
+                            void this.#invalidateSession(error, "rejected");
+                        }
+                        settleEstablishment({ ok: false, error });
+                    }
+                    else {
+                        const authenticationRejected = rejectionCode === "authentication" ||
+                            rejectionCode === "authorization";
+                        if (authenticationRejected) {
+                            enterAuthRequired();
+                        }
+                        else {
+                            active.acceptingEvents = false;
+                            active.terminal = true;
+                            active.recoveryRevision += 1;
+                            try {
+                                active.socket.disconnect();
+                            }
+                            catch {
+                                // Subscription failure is already terminal for this episode.
+                            }
+                            lifecycle("subscription-failed");
+                        }
+                        report(error, authenticationRejected ? "authentication" : "subscription");
+                        if (authenticationRejected) {
+                            void this.#invalidateSession(error, "rejected");
+                        }
+                    }
+                    return;
+                }
+                if (!reconnect) {
+                    joinPending = false;
+                    subscriptionEstablished = true;
+                    for (const notification of pendingNotifications.splice(0)) {
+                        if (notification.kind === "update")
+                            next(notification.update);
+                        else
+                            notifyError(notification.error);
+                    }
+                    settleEstablishment?.({
+                        ok: true,
+                        value: {
+                            dispose: () => {
+                                if (!active.active)
+                                    return;
+                                active.active = false;
+                                active.cleanup();
+                                this.#subscriptions.delete(active);
+                            },
+                        },
+                    });
+                    resolveError("connection");
+                    resolveError("authentication");
+                    if (this.#profile.kind === "current-server" &&
+                        acknowledgement.empty) {
+                        lifecycle("degraded", {
+                            assurance: "best-effort",
+                            complete: false,
+                            reason: "initial-rest-preflight",
+                            source: "rest-rebase",
+                        }, this.#now() - joinStartedAt);
+                    }
+                    else {
+                        lifecycle("active", {
+                            complete: true,
+                            ...(acknowledgement.cursor === undefined
+                                ? {}
+                                : { cursor: acknowledgement.cursor }),
+                        }, this.#now() - joinStartedAt);
+                    }
+                    currentServerSession = undefined;
+                    active.acceptingEvents = true;
+                    flushRealtime();
+                    return;
+                }
+                joinPending = false;
+                const joinLatencyMs = this.#now() - joinStartedAt;
+                lifecycle("recovering", {
+                    complete: false,
+                    ...(acknowledgement.cursor === undefined
+                        ? {}
+                        : { cursor: acknowledgement.cursor }),
+                    ...(acknowledgement.recoveryComplete
+                        ? {}
+                        : { reason: "server-replay-contract-unavailable" }),
+                }, joinLatencyMs);
+                active.acceptingEvents = true;
+                flushRealtime();
+                if (this.#profile.kind === "current-server" &&
+                    !acknowledgement.recoveryComplete) {
+                    const recoverySession = currentServerSession;
+                    currentServerSession = undefined;
+                    if (recoverySession === undefined) {
+                        report(this.#error("authentication", "TFRobot reconnect did not provide a session for REST rebase", true, errorConversationId()), "recovery");
+                        return;
+                    }
+                    void rebaseCurrentServer(recoveryRevision, runRevision, recoverySession, rebaseCheckpoint, rebaseRealtimeRevision)
+                        .then((outcome) => {
+                        if (!active.active ||
+                            !this.#subscriptions.has(active) ||
+                            !active.socket.connected ||
+                            active.recoveryRevision !== recoveryRevision) {
+                            return;
+                        }
+                        if (outcome.kind === "auth-required") {
+                            enterAuthRequired();
+                            return;
+                        }
+                        if (outcome.kind !== "success")
+                            return;
+                        resolveError("connection");
+                        resolveError("recovery");
+                        resolveError("authentication");
+                        active.manualReconnectAttempted = false;
+                        active.manualReconnectPending = false;
+                        active.authRequired = false;
+                        active.terminal = false;
+                        lifecycle("degraded", {
+                            assurance: "best-effort",
+                            complete: false,
+                            reason: outcome.reason,
+                            source: "rest-rebase",
+                        }, joinLatencyMs);
+                    })
+                        .catch(() => {
+                        report(this.#error("unknown", "TFRobot REST rebase failed unexpectedly", true, errorConversationId()), "recovery");
+                    });
+                    return;
+                }
+                currentServerSession = undefined;
+                void this.#reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, runRevision, next, report)
+                    .then((outcome) => {
+                    if (outcome === "auth-required") {
+                        enterAuthRequired();
+                        return;
+                    }
+                    if ((outcome !== "success" && outcome !== "superseded-by-realtime") ||
+                        !acknowledgement.recoveryComplete) {
+                        return;
+                    }
+                    resolveError("connection");
+                    resolveError("recovery");
+                    resolveError("authentication");
+                    active.manualReconnectAttempted = false;
+                    active.manualReconnectPending = false;
+                    active.authRequired = false;
+                    active.terminal = false;
+                    lifecycle("active", {
+                        complete: true,
+                        ...(acknowledgement.cursor === undefined
+                            ? {}
+                            : { cursor: acknowledgement.cursor }),
+                    }, joinLatencyMs);
+                })
+                    .catch(() => {
+                    active.acceptingEvents = false;
+                    active.terminal = true;
+                    try {
+                        active.socket.disconnect();
+                    }
+                    catch {
+                        // Offline is already terminal for this subscription episode.
+                    }
+                    lifecycle("offline");
+                    report(this.#error("unknown", "TFRobot reconnect reconciliation failed", true, errorConversationId()), "recovery");
                 });
+            };
+            const joinDeadlineAt = reconnect
+                ? this.#now() + RECONNECT_JOIN_TIMEOUT_MS
+                : options.deadlineAt;
+            joinTimeout = setTimeout(() => {
+                joinTimeout = undefined;
+                if (!active.active || active.recoveryRevision !== recoveryRevision) {
+                    return;
+                }
+                active.recoveryRevision += 1;
+                joinPending = false;
+                pendingRealtimeActions.length = 0;
+                const error = createGatewayDeadlineExceededError(errorConversationId());
+                if (settleEstablishment !== undefined) {
+                    lifecycle("subscription-failed");
+                    settleEstablishment({ ok: false, error });
+                }
+                else {
+                    if (active.manualReconnectPending)
+                        enterAuthRequired();
+                    else {
+                        active.acceptingEvents = false;
+                        active.terminal = true;
+                        lifecycle("subscription-failed");
+                    }
+                    report(error, active.manualReconnectPending ? "connection" : "subscription");
+                    try {
+                        active.socket.disconnect();
+                    }
+                    catch {
+                        // The failed join attempt is already invalidated.
+                    }
+                }
+            }, Math.min(MAX_TIMER_DELAY, Math.max(0, joinDeadlineAt - this.#now())));
+            try {
+                socket.emit("join_conversation", { conversation_id: conversationId }, settleJoin);
             }
             catch (reason) {
                 const error = this.#transportError(reason, "Unable to join the TFRobot conversation", conversationId, credentialValues);
@@ -321,112 +982,97 @@ export class TFRobotSocketClient {
                     settleEstablishment({ ok: false, error });
                 }
                 else {
-                    report(error);
+                    report(error, "subscription");
                     active.active = false;
                     active.cleanup();
-                    if (this.#active === active)
-                        this.#active = undefined;
+                    this.#subscriptions.delete(active);
                 }
                 return;
             }
-            if (settleEstablishment !== undefined &&
-                isGatewayDeadlineExceeded(options, this.#now())) {
-                settleEstablishment({
-                    ok: false,
-                    error: createGatewayDeadlineExceededError(errorConversationId()),
-                });
-                return;
-            }
-            settleEstablishment?.({
-                ok: true,
-                value: {
-                    dispose: () => {
-                        if (!active.active)
-                            return;
-                        active.active = false;
-                        active.cleanup();
-                        if (this.#active === active)
-                            this.#active = undefined;
-                    },
-                },
-            });
-            if (reconnect) {
-                void this.#reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, next, report).catch(() => {
-                    report(this.#error("unknown", "TFRobot reconnect reconciliation failed", true, errorConversationId()));
-                });
-            }
         });
         add("chat_message", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = messageDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot chat_message payload", false, errorConversationId()));
-                return;
-            }
-            mapAndNext("TFRobot chat_message could not be normalized", () => mapMessageUpdate(parsed.data));
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = messageDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot chat_message payload", false, errorConversationId()));
+                    return;
+                }
+                mapAndNext("TFRobot chat_message could not be normalized", () => mapMessageUpdate(parsed.data));
+            });
         });
         add("chat_event", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = eventDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot chat_event payload", false, errorConversationId()));
-                return;
-            }
-            mapAndNext("TFRobot chat_event could not be normalized", () => mapEventUpdate(parsed.data));
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = eventDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot chat_event payload", false, errorConversationId()));
+                    return;
+                }
+                mapAndNext("TFRobot chat_event could not be normalized", () => mapEventUpdate(parsed.data));
+            });
         });
         add("conversation_state_changed", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = stateChangedDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot conversation_state_changed payload", false, errorConversationId()));
-                return;
-            }
-            const targetConversationId = String(parsed.data.conversationId);
-            if (targetConversationId !== conversationId &&
-                targetConversationId !== errorConversationId()) {
-                return;
-            }
-            active.recoveryRevision += 1;
-            mapAndNext("TFRobot run state could not be normalized", () => {
-                const run = mapRun(targetConversationId, {
-                    working: parsed.data.state === "working",
-                    taskId: parsed.data.taskId,
-                });
-                this.#runs.set(targetConversationId, run);
-                return chatUpdateSchema.parse({
-                    kind: "run.replace",
-                    conversationId: targetConversationId,
-                    run,
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = stateChangedDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot conversation_state_changed payload", false, errorConversationId()));
+                    return;
+                }
+                const targetConversationId = String(parsed.data.conversationId);
+                if (targetConversationId !== conversationId &&
+                    targetConversationId !== errorConversationId()) {
+                    return;
+                }
+                active.runRevision += 1;
+                mapAndNext("TFRobot run state could not be normalized", () => {
+                    const run = mapRun(targetConversationId, {
+                        working: parsed.data.state === "working",
+                        taskId: parsed.data.taskId,
+                    });
+                    this.#runs.set(targetConversationId, run);
+                    return chatUpdateSchema.parse({
+                        kind: "run.replace",
+                        conversationId: targetConversationId,
+                        run,
+                    });
                 });
             });
         });
         add("chat_error", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = chatErrorEventDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot chat_error payload", false, errorConversationId()));
-                return;
-            }
-            const targetConversationId = String(parsed.data.conversationId);
-            if (targetConversationId !== conversationId &&
-                targetConversationId !== errorConversationId()) {
-                return;
-            }
-            report(this.#error("server", typeof parsed.data.error === "string"
-                ? parsed.data.error
-                : "TFRobot run failed", false, targetConversationId, parsed.data, credentialValues));
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = chatErrorEventDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot chat_error payload", false, errorConversationId()));
+                    return;
+                }
+                const targetConversationId = String(parsed.data.conversationId);
+                if (targetConversationId !== conversationId &&
+                    targetConversationId !== errorConversationId()) {
+                    return;
+                }
+                report(this.#error("server", typeof parsed.data.error === "string"
+                    ? parsed.data.error
+                    : "TFRobot run failed", false, targetConversationId, parsed.data, credentialValues), "domain");
+            });
         });
         add("error", (payload) => {
-            const parsed = socketProtocolErrorDtoSchema.safeParse(sanitizePayload(payload));
-            report(this.#error("validation", parsed.success && typeof parsed.data.message === "string"
-                ? parsed.data.message
-                : "TFRobot Socket protocol error", false, conversationId, undefined, credentialValues));
+            dispatchRealtime(() => {
+                const parsed = socketProtocolErrorDtoSchema.safeParse(sanitizePayload(payload));
+                report(this.#error("validation", parsed.success && typeof parsed.data.message === "string"
+                    ? parsed.data.message
+                    : "TFRobot Socket protocol error", false, conversationId, undefined, credentialValues));
+            });
         });
         add("connect_error", (reason) => {
+            if (!active.active || active.terminal)
+                return;
             const injectedError = chatErrorSchema.safeParse(reason);
             const rejectionCode = socketAuthRejectionCode(reason);
             const error = authenticationFailure !== undefined
@@ -448,23 +1094,82 @@ export class TFRobotSocketClient {
                 settleEstablishment({ ok: false, error });
                 return;
             }
-            report(error);
+            if (active.manualReconnectPending) {
+                enterAuthRequired();
+                report(error, error.code === "authentication" || error.code === "authorization"
+                    ? "authentication"
+                    : "connection");
+                return;
+            }
+            if (error.code === "authentication" || error.code === "authorization") {
+                enterAuthRequired();
+            }
+            report(error, error.code === "authentication" || error.code === "authorization"
+                ? "authentication"
+                : "connection");
         });
         add("disconnect", (reason) => {
             if (reason === "io client disconnect")
                 return;
+            if (active.terminal)
+                return;
+            active.acceptingEvents = false;
+            joinPending = false;
+            pendingRealtimeActions.length = 0;
+            if (joinTimeout !== undefined) {
+                clearTimeout(joinTimeout);
+                joinTimeout = undefined;
+            }
             active.recoveryRevision += 1;
+            lifecycle("reconnecting");
             const injectedError = chatErrorSchema.safeParse(reason);
             report(injectedError.success
                 ? sanitizeCredentialError(injectedError.data, credentialValues)
-                : this.#error("network", `TFRobot Socket disconnected: ${String(reason)}`, true, conversationId, undefined, credentialValues));
-        });
-        const anyListener = (eventName, payload) => {
-            if (KNOWN_EVENTS.has(eventName))
+                : this.#error("network", `TFRobot Socket disconnected: ${String(reason)}`, true, conversationId, undefined, credentialValues), "connection");
+            if (reason !== "io server disconnect")
                 return;
-            if (belongsToForeignConversation(payload, conversationId))
+            if (active.manualReconnectAttempted) {
+                enterAuthRequired();
                 return;
-            mapAndNext("Unknown TFRobot Socket event could not be normalized", () => mapUnknownSocketEvent(sanitizeCredentialText(eventName, credentialValues), sanitizePayload(payload), errorConversationId(), this.#now()));
+            }
+            active.manualReconnectAttempted = true;
+            active.manualReconnectPending = true;
+            const invalidationRevision = active.recoveryRevision;
+            const invalidationError = this.#error("authentication", "TFRobot Socket session was invalidated by the server", true, errorConversationId());
+            void awaitBounded(() => this.#invalidateSession(invalidationError, "unknown"), {
+                deadlineAt: this.#now() + RECONNECT_AUTH_TIMEOUT_MS,
+                now: this.#now,
+                signal: connectionAbort.signal,
+            }).then((outcome) => {
+                if (!active.active ||
+                    active.socket.connected ||
+                    active.authRequired ||
+                    !active.manualReconnectPending ||
+                    active.recoveryRevision !== invalidationRevision) {
+                    return;
+                }
+                if (outcome.kind !== "value" || !outcome.value) {
+                    report(this.#error("authentication", "Unable to invalidate the TFRobot Socket session", false, errorConversationId()), "authentication");
+                    enterAuthRequired();
+                    return;
+                }
+                try {
+                    active.socket.connect();
+                }
+                catch (reconnectError) {
+                    report(this.#transportError(reconnectError, "Unable to reconnect the TFRobot Socket transport", conversationId, credentialValues), "authentication");
+                    enterAuthRequired();
+                }
+            });
+        });
+        const anyListener = (eventName, payload) => {
+            dispatchRealtime(() => {
+                if (KNOWN_EVENTS.has(eventName))
+                    return;
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                mapAndNext("Unknown TFRobot Socket event could not be normalized", () => mapUnknownSocketEvent(sanitizeCredentialText(eventName, credentialValues), sanitizePayload(payload), errorConversationId(), this.#now()));
+            });
         };
         if (setupFailure === undefined) {
             try {
@@ -476,6 +1181,10 @@ export class TFRobotSocketClient {
         }
         const cleanup = () => {
             connectionAbort.abort();
+            if (joinTimeout !== undefined) {
+                clearTimeout(joinTimeout);
+                joinTimeout = undefined;
+            }
             for (const [eventName, listener] of listeners) {
                 try {
                     socket.off(eventName, listener);
@@ -497,18 +1206,24 @@ export class TFRobotSocketClient {
                 // Adapter ownership is cleared even if an injected transport misbehaves.
             }
             firstAuth = undefined;
+            currentServerSession = undefined;
             credentialValues.clear();
+            pendingNotifications.length = 0;
+            pendingRealtimeActions.length = 0;
         };
         if (setupFailure !== undefined) {
             const error = this.#transportError(setupFailure.reason, "Unable to configure the TFRobot Socket transport", conversationId, credentialValues);
             cleanup();
+            clearPendingEstablishment();
             return {
                 ok: false,
                 error,
             };
         }
         const active = {
+            acceptingEvents: true,
             active: true,
+            authRequired: false,
             cancelEstablishment: () => {
                 settleEstablishment?.({
                     ok: false,
@@ -517,11 +1232,21 @@ export class TFRobotSocketClient {
             },
             cleanup,
             conversationId,
+            generation,
+            manualReconnectAttempted: false,
+            manualReconnectPending: false,
             observer,
+            reconnectAttempt: 0,
+            realtimeIdentityRevisions: new Map(),
+            realtimeRevision: 0,
             recoveryRevision: 0,
+            runRevision: 0,
             socket,
+            subscriptionId,
+            terminal: false,
         };
-        this.#active = active;
+        this.#subscriptions.add(active);
+        this.#establishing = active;
         return new Promise((resolve) => {
             let settled = false;
             const settle = (result) => {
@@ -529,12 +1254,14 @@ export class TFRobotSocketClient {
                     return;
                 settled = true;
                 settleEstablishment = undefined;
+                clearPendingEstablishment();
+                if (this.#establishing === active)
+                    this.#establishing = undefined;
                 clearTimeout(timeout);
                 if (!result.ok) {
                     active.active = false;
                     active.cleanup();
-                    if (this.#active === active)
-                        this.#active = undefined;
+                    this.#subscriptions.delete(active);
                 }
                 resolve(result);
             };
@@ -553,6 +1280,7 @@ export class TFRobotSocketClient {
                 return;
             }
             try {
+                lifecycle("connecting");
                 socket.connect();
             }
             catch (reason) {
@@ -574,24 +1302,54 @@ export class TFRobotSocketClient {
         if (this.#disposed)
             return;
         this.#disposed = true;
-        this.#deactivateCurrent();
+        this.#cancelEstablishment();
+        for (const subscription of this.#subscriptions) {
+            subscription.active = false;
+            subscription.cleanup();
+        }
+        this.#subscriptions.clear();
+        this.#recoveryCheckpoints.clear();
         this.#runs.clear();
     }
+    rememberSnapshot(snapshot) {
+        if (this.#disposed)
+            return;
+        const conversationId = snapshot.conversation.id;
+        this.#runs.set(conversationId, snapshot.run);
+        const checkpoint = this.#recoveryCheckpoints.get(conversationId) ?? new Set();
+        for (const identity of recoveryIdentitiesOfSnapshot(snapshot)) {
+            rememberBoundedSetValue(checkpoint, identity);
+        }
+        this.#recoveryCheckpoints.set(conversationId, checkpoint);
+    }
     rememberRun(conversationId, run) {
         if (this.#disposed)
             return;
         this.#runs.set(conversationId, run);
     }
-    #deactivateCurrent() {
-        this.#establishmentAbort?.abort();
-        this.#establishmentAbort = undefined;
-        const current = this.#active;
-        if (current === undefined)
+    forgetConversation(conversationId) {
+        if (this.#disposed)
             return;
-        current.cancelEstablishment();
-        current.active = false;
-        current.cleanup();
-        this.#active = undefined;
+        if (this.#pendingEstablishment?.conversationId === conversationId ||
+            this.#establishing?.conversationId === conversationId) {
+            this.#cancelEstablishment();
+        }
+        for (const subscription of [...this.#subscriptions]) {
+            if (subscription.conversationId !== conversationId)
+                continue;
+            subscription.active = false;
+            subscription.recoveryRevision += 1;
+            subscription.cleanup();
+            this.#subscriptions.delete(subscription);
+        }
+        this.#recoveryCheckpoints.delete(conversationId);
+        this.#runs.delete(conversationId);
+    }
+    #cancelEstablishment() {
+        this.#pendingEstablishment?.abort.abort();
+        this.#pendingEstablishment = undefined;
+        this.#establishing?.cancelEstablishment();
+        this.#establishing = undefined;
     }
     #defaultNamespaceUrl(baseUrl) {
         const url = new URL(baseUrl);
@@ -600,7 +1358,7 @@ export class TFRobotSocketClient {
         url.hash = "";
         return url.toString().replace(/\/$/u, "");
     }
-    async #getSocketAuth(conversationId, purpose) {
+    async #getSocketSession(conversationId, purpose) {
         const session = await this.#options.sessionProvider.getSession({
             purpose,
             operation: "subscribe",
@@ -609,19 +1367,30 @@ export class TFRobotSocketClient {
         if (!isValidTFRobotSession(session)) {
             throw new TypeError("SessionProvider returned invalid TFRobot credentials");
         }
-        return authOf(session);
+        return session;
     }
-    async #reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, next, report) {
+    async #reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, runRevision, next, report) {
         const result = await this.#reconnectStatusLoader(conversationId);
         if (!active.active ||
-            this.#active !== active ||
+            !this.#subscriptions.has(active) ||
             !active.socket.connected ||
             active.recoveryRevision !== recoveryRevision) {
-            return;
+            return "failure";
         }
         if (!result.ok) {
-            report(sanitizeCredentialError(result.error, credentialValues));
-            return;
+            const error = sanitizeCredentialError(result.error, credentialValues);
+            if (error.code === "authentication" || error.code === "authorization") {
+                report(error, "authentication");
+                return "auth-required";
+            }
+            if (active.runRevision !== runRevision) {
+                return "superseded-by-realtime";
+            }
+            report(error, "recovery");
+            return "failure";
+        }
+        if (active.runRevision !== runRevision) {
+            return "superseded-by-realtime";
         }
         try {
             const updateConversationId = sanitizeCredentialText(conversationId, credentialValues);
@@ -629,16 +1398,18 @@ export class TFRobotSocketClient {
             const run = mapRun(updateConversationId, safeStatus);
             const previous = this.#runs.get(conversationId);
             this.#runs.set(conversationId, run);
-            if (sameRun(previous, run))
-                return;
-            next(chatUpdateSchema.parse({
-                kind: "run.replace",
-                conversationId: updateConversationId,
-                run,
-            }));
+            if (!sameRun(previous, run)) {
+                next(chatUpdateSchema.parse({
+                    kind: "run.replace",
+                    conversationId: updateConversationId,
+                    run,
+                }));
+            }
+            return "success";
         }
         catch {
-            report(this.#error("validation", "Reconnected TFRobot run status could not be normalized", false, conversationId, undefined, credentialValues));
+            report(this.#error("validation", "Reconnected TFRobot run status could not be normalized", false, conversationId, undefined, credentialValues), "recovery");
+            return "failure";
         }
     }
     async #invalidateSession(error, reason) {
@@ -647,9 +1418,10 @@ export class TFRobotSocketClient {
                 reason: reason ?? (error.code === "authorization" ? "forbidden" : "expired"),
                 error,
             });
+            return true;
         }
         catch {
-            // Host refresh/login failures must not replace the Socket error.
+            return false;
         }
     }
     #transportError(reason, fallback, conversationId, credentialValues = []) {