@clawling/clawchat-plugin-openclaw 2026.5.12-39 → 2026.5.13-dev.1

package/dist/src/runtime.js

@@ -5,6 +5,7 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient } from "./client.js";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { ClawlingApiError } from "./api-types.js";
+import { RefreshManager } from "./refresh-manager.js";
 import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, hasOpenclawClawlingConnectCredentials, } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { fetchInboundMedia } from "./media-runtime.js";
@@ -12,7 +13,7 @@ import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.js";
 import { flushAlignedOutboundQueue, getAlignedOutboundQueueSize, sendOpenclawClawlingText, setAlignedOutboundLogContext, } from "./outbound.js";
 import { formatWsLog } from "./ws-log.js";
-import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.js";
+import { createNotifySignalObserver, createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.js";
 import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
 import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.js";
 import { loadClawChatPromptMetadata, renderClawChatProfilePrompt, resolveSenderRelation, } from "./profile-prompt.js";
@@ -41,9 +42,38 @@ const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
     "nevermind",
 ]);
 const GROUP_OWNER_ATTENTION_TITLE = "requires owner attention";
+// §C.1 — user-visible message emitted on permanent token expiry. Kept
+// byte-identical to the Hermes plugin (parity spec §C.1.4).
+const CLAWCHAT_TOKEN_EXPIRED_MESSAGE = "ClawChat token expired and could not be refreshed. Re-pair with `/clawchat-activate <code>`.";
+const CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR = "token expired — re-pair required";
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+/**
+ * §A.2 — classify a WS `hello-fail` reason for refresh gating.
+ *  - "token-rejected": reason names an authentication failure → refresh.
+ *  - "auth-unavailable": 5xx auth-backend outage → backoff, DO NOT refresh.
+ *  - "generic": unattributed → refresh only if the token is at/near expiry.
+ *
+ * `auth service unavailable` is already split off by the ws-client into a
+ * TransportError (backoff), but we classify defensively here too.
+ */
+export function classifyHelloFailReason(reason) {
+    const r = (reason || "").toLowerCase();
+    if (/auth service unavailable|temporarily unavailable/.test(r))
+        return "auth-unavailable";
+    if (/authentication failed|invalid token|token expired|unauthorized|auth failed|invalid credentials/.test(r)) {
+        return "token-rejected";
+    }
+    return "generic";
+}
+/** Read `channels.<CHANNEL_ID>.refreshToken` from a live config, or null. */
+function readConfigRefreshToken(cfg) {
+    const channels = cfg.channels;
+    const channel = isRecord(channels) ? channels[CHANNEL_ID] : undefined;
+    const refreshToken = isRecord(channel) ? channel.refreshToken : undefined;
+    return typeof refreshToken === "string" && refreshToken.trim() ? refreshToken.trim() : null;
+}
 function withFullVerboseDispatchConfig(cfg, agentId) {
     const cfgRecord = cfg;
     const agents = isRecord(cfgRecord.agents) ? cfgRecord.agents : {};
@@ -214,7 +244,12 @@ function metadataScopesFromEnvelope(env) {
     return Array.isArray(scope) ? scope.filter((item) => typeof item === "string") : [];
 }
 function shouldRefreshBehaviorForScopes(scopes) {
-    return scopes.includes("behavior");
+    // §9.3: empty/absent scope ⇒ "refetch everything"; unknown scope strings must
+    // also trigger a refresh. Only the known non-behavior scopes (title,
+    // description) leave agent behavior untouched.
+    if (scopes.length === 0)
+        return true;
+    return scopes.some((scope) => scope !== "title" && scope !== "description");
 }
 function shouldRefreshConversationForScopes(scopes) {
     if (scopes.length === 0)
@@ -272,6 +307,17 @@ function buildActivationBootstrapEnvelope(params) {
         },
     };
 }
+/**
+ * §A.3/§A.4 — max consecutive refresh-driven reconnects within
+ * `REFRESH_RECONNECT_WINDOW_MS` before we abandon the refresh loop and fall back
+ * to plain transport backoff (or auto-logout on a permanent reject). Bounds a
+ * server that keeps rotating-then-rejecting fresh tokens.
+ */
+export const MAX_REFRESH_RECONNECTS = 3;
+export const REFRESH_RECONNECT_WINDOW_MS = 5 * 60_000;
+/** §B — default transport-backoff delay before a reactive re-enter (capped 30s). */
+export const TRANSPORT_BACKOFF_BASE_MS = 1_000;
+export const TRANSPORT_BACKOFF_MAX_MS = 30_000;
 function resolveConnectionStore(params, runtime) {
     if (params.store !== undefined)
         return params.store;
@@ -392,15 +438,81 @@ export async function startOpenclawClawlingGateway(params) {
     if (!activationAccount)
         return;
     account = activationAccount.account;
+    // §A.0 — fallback expiry source. Prefer the SQLite `activated_at`; null when
+    // the credentials came from config (no activation row yet) — in that case the
+    // refresh manager relies on the JWT `exp` alone.
+    let activatedAtMs = activationAccount.source === "sqlite" && store?.getActivationCredentials
+        ? store.getActivationCredentials({ platform: "openclaw", accountId })?.activatedAt ?? null
+        : null;
     let conversationApiClient;
+    const buildConversationApiClient = () => createOpenclawClawlingApiClient({
+        baseUrl: account.baseUrl,
+        mediaBaseUrl: account.mediaBaseUrl,
+        token: account.token,
+        userId: account.userId,
+    });
+    // §A.2.1 — forward reference to the single-flight REST refresh wrapper; set
+    // once the refresh manager exists. Until then, calls run un-wrapped.
+    let restWithRefresh = null;
+    // Returns a proxy whose every method call runs through `restWithRefresh`, so a
+    // 401/403 transparently triggers one single-flight refresh + retry. The proxy
+    // reads the cached client lazily on each call so a post-refresh rebuild is
+    // picked up automatically.
     const getConversationApiClient = () => {
-        conversationApiClient ??= createOpenclawClawlingApiClient({
-            baseUrl: account.baseUrl,
-            mediaBaseUrl: account.mediaBaseUrl,
-            token: account.token,
-            userId: account.userId,
+        return new Proxy({}, {
+            get: (_target, prop) => {
+                return (...args) => {
+                    const invoke = () => {
+                        conversationApiClient ??= buildConversationApiClient();
+                        const fn = conversationApiClient[prop];
+                        if (typeof fn !== "function") {
+                            throw new TypeError(`clawchat api-client has no method ${String(prop)}`);
+                        }
+                        return fn.apply(conversationApiClient, args);
+                    };
+                    return restWithRefresh
+                        ? restWithRefresh(() => Promise.resolve(invoke()))
+                        : invoke();
+                };
+            },
+        });
+    };
+    // Rebuilt after every in-memory token swap so REST calls use the fresh token.
+    const invalidateConversationApiClient = () => {
+        conversationApiClient = undefined;
+    };
+    const resolveMutateConfigFile = () => {
+        if (params.mutateConfigFile)
+            return params.mutateConfigFile;
+        const runtimeConfig = runtime.config;
+        return typeof runtimeConfig?.mutateConfigFile === "function"
+            ? runtimeConfig.mutateConfigFile
+            : undefined;
+    };
+    // §0/§C.1 — write the channel-config `token`/`refreshToken` keys. `tokens=null`
+    // blanks them (auto-logout); otherwise persists the rotated pair.
+    const persistConfigTokens = async (tokens) => {
+        const mutateConfigFile = resolveMutateConfigFile();
+        if (!mutateConfigFile) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw config persistence unavailable; cannot ${tokens ? "rotate" : "clear"} tokens in config`);
+            return;
+        }
+        await mutateConfigFile({
+            afterWrite: { mode: "none", reason: "clawchat-plugin-openclaw token refresh" },
+            mutate(draft) {
+                const channels = (draft.channels ?? {});
+                const existing = (channels[CHANNEL_ID] ?? {});
+                const nextSection = {
+                    ...existing,
+                    token: tokens ? tokens.accessToken : "",
+                    refreshToken: tokens ? tokens.refreshToken : "",
+                };
+                Object.assign(draft, {
+                    ...draft,
+                    channels: { ...channels, [CHANNEL_ID]: nextSection },
+                });
+            },
         });
-        return conversationApiClient;
     };
     let lastHelloFailTraceId = "-";
     let lastHelloFailReason = "";
@@ -411,6 +523,129 @@ export async function startOpenclawClawlingGateway(params) {
     let authFailureLogged = false;
     let closingForAbort = false;
     let wsReady = false;
+    // True once this gateway attempt reached "connected" at least once — used to
+    // route a later auth-fail through the live-session reactive refresh path
+    // rather than the initial-connect catch.
+    let wsReadyEverThisAttempt = false;
+    // §D — set when a refresh succeeded and we are closing the live WS to
+    // reconnect with the new token; suppresses the auth-failed teardown path and
+    // drives a clean re-enter into the gateway with the rotated account.
+    let reconnectWithRefreshedToken = false;
+    // §C — set once auto-logout has fired so we don't double-emit or reconnect.
+    let autoLoggedOut = false;
+    // §E — connect-time device id for `X-Device-Id` on refresh. Prefer the value
+    // recorded in SQLite at connect; backfill legacy rows (no column) to the
+    // deterministic constant `CHANNEL_ID` actually sent by `authHeaders`.
+    const refreshDeviceId = (activationAccount.source === "sqlite" && store?.getActivationCredentials
+        ? store.getActivationCredentials({ platform: "openclaw", accountId })?.deviceId
+        : null) || CHANNEL_ID;
+    // §C — auto-logout on permanent refresh failure. Blank creds in BOTH stores
+    // (KEEP identity), flip not-configured via the auth-failure status path, and
+    // emit the user-visible message. Idempotent.
+    const performAutoLogout = async (info) => {
+        if (autoLoggedOut)
+            return;
+        autoLoggedOut = true;
+        log?.error?.(`[${accountId}] clawchat-plugin-openclaw auto-logout (token permanently expired) code=${info.code}: ${info.message}`);
+        // SQLite: blank access/refresh, keep user/owner/device for re-pair.
+        if (store?.clearActivationCredentials) {
+            recordConnection("clear activation credentials", () => store.clearActivationCredentials?.({ platform: "openclaw", accountId }));
+        }
+        // Config: blank token/refreshToken keys.
+        try {
+            await persistConfigTokens(null);
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw failed to clear config credentials on auto-logout: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Flip not-configured (existing auth-failure status path) with the re-pair
+        // hint as `lastError`.
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            configured: false,
+            running: false,
+            lastError: CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR,
+        });
+        // User-visible notification (in addition to logs). Best-effort; never throws.
+        emitUserVisibleAuthLogout();
+    };
+    // §C.1.4 — surface the permanent-expiry message to the user/operator. The
+    // plugin has no guaranteed live chat target after creds are cleared, so we
+    // route through the runtime notification surface when present and always log.
+    const emitUserVisibleAuthLogout = () => {
+        log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${CLAWCHAT_TOKEN_EXPIRED_MESSAGE}`);
+        try {
+            const notify = runtime.notifications?.notify;
+            if (typeof notify === "function") {
+                notify({ level: "error", message: CLAWCHAT_TOKEN_EXPIRED_MESSAGE });
+            }
+        }
+        catch {
+            // Best effort only.
+        }
+    };
+    // The refresh token is not part of the resolved account; source it from
+    // SQLite first (authoritative after a rotation) then the config channel
+    // section. Kept in a mutable cell so a swap updates it in place.
+    let latestRefreshToken = (activationAccount.source === "sqlite" && store?.getActivationCredentials
+        ? store.getActivationCredentials({ platform: "openclaw", accountId })?.refreshToken
+        : null) ?? readConfigRefreshToken(cfg);
+    const refreshManager = new RefreshManager({
+        baseUrl: account.baseUrl,
+        deviceId: refreshDeviceId,
+        getAccessToken: () => account.token,
+        getRefreshToken: () => latestRefreshToken,
+        persistRotatedTokens: async (tokens) => {
+            // §0 — persist to BOTH stores BEFORE the in-memory swap. A failure in
+            // EITHER store must REJECT so the manager skips the in-memory swap and
+            // treats the refresh as transient (keep the current tokens, back off). Do
+            // NOT swallow the SQLite write error: `rotateActivationTokens` returns
+            // `null` when its internal `write()` caught an exception (a real write
+            // failure), `false` only when no activation row exists yet (config-sourced
+            // agent — legitimately nothing to update). A swallowed write failure must
+            // not leave the SQLite row holding the now-dead refresh token while the
+            // in-memory token is rotated, which would brick a sqlite-sourced agent on
+            // restart.
+            if (store?.rotateActivationTokens) {
+                const rotateResult = store.rotateActivationTokens({
+                    platform: "openclaw",
+                    accountId,
+                    accessToken: tokens.accessToken,
+                    refreshToken: tokens.refreshToken,
+                });
+                if (rotateResult === null) {
+                    throw new Error("clawchat-plugin-openclaw sqlite rotate activation tokens failed");
+                }
+            }
+            // A config write failure rejects out of `mutateConfigFile` and propagates
+            // here, which is what we want — persistence incomplete ⇒ no swap.
+            await persistConfigTokens(tokens);
+        },
+        swapInMemoryTokens: (tokens) => {
+            account = { ...account, token: tokens.accessToken, configured: true };
+            latestRefreshToken = tokens.refreshToken;
+            activatedAtMs = Date.now();
+            invalidateConversationApiClient();
+        },
+        onPermanentFailure: performAutoLogout,
+        // §A.1/§D — proactive-timer success closes the live WS and re-enters with the
+        // rotated token. The running ws-client captured the OLD token at `connect`
+        // time, so the in-memory swap alone never reaches a `connect` envelope.
+        onProactiveRefreshed: async () => {
+            await runRefreshReconnect("proactive-timer");
+        },
+        ...(params.refreshFetchImpl ? { fetchImpl: params.refreshFetchImpl } : {}),
+        ...(params.refreshSetTimer ? { setTimer: params.refreshSetTimer } : {}),
+        ...(params.refreshClearTimer ? { clearTimer: params.refreshClearTimer } : {}),
+        ...(params.refreshJitter ? { jitter: params.refreshJitter } : {}),
+        log,
+    });
+    // §A.3/§A.4 — carry the single-flight latch + min-interval across re-enters so
+    // the guards bound a rotate-then-reject loop instead of resetting each time.
+    if (params.refreshManagerState) {
+        refreshManager.restoreState(params.refreshManagerState);
+    }
     let currentConnectionId = null;
     let currentConnectionFinished = false;
     const reconnectTracker = createReconnectTracker({
@@ -530,7 +765,10 @@ export async function startOpenclawClawlingGateway(params) {
         const memoryRoot = resolveMemoryRootForPeer(peer);
         if (!memoryRoot)
             return;
-        if (refreshBehavior) {
+        // §9.3: agent behavior is per-agent metadata that lives only on the agent's
+        // DIRECT conversation — never refetch it for a group invalidation, even on a
+        // "refetch everything" (empty/unknown) scope.
+        if (refreshBehavior && peer.kind === "direct") {
             await refreshAgentBehavior({
                 source: "metadata_invalidation",
                 ...(version !== undefined ? { metadataVersion: version } : {}),
@@ -600,8 +838,36 @@ export async function startOpenclawClawlingGateway(params) {
             log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
         });
     };
+    // §A.4 — startup refresh-if-near-expiry, BEFORE the first WS connect. Recovers
+    // a long-stopped pod with no manual re-pair. On a permanent refresh failure
+    // auto-logout immediately and skip the doomed connect.
+    if (!abortSignal.aborted &&
+        latestRefreshToken &&
+        refreshManager.isNearExpiry(activatedAtMs)) {
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw access token near expiry at startup; refreshing before connect`);
+        const startupOutcome = await refreshManager.refresh("startup-near-expiry");
+        if (abortSignal.aborted)
+            return;
+        if (startupOutcome.kind === "permanent") {
+            // Auto-logout already performed by the manager's onPermanentFailure.
+            return;
+        }
+        // success swaps the in-memory token in place; transient/skipped just connect
+        // with the current token (the WS handshake will then drive reactive refresh).
+    }
+    // Reuse the device id the server resolved on a previous connection so a pod
+    // restart (fresh hostname → fresh hostname-derived id) does not present a
+    // brand-new device, which would force a full inbox replay and orphan the
+    // prior device's cursor. Persisted from `hello-ok` via markConnectionReady.
+    const persistedDeviceId = store?.getLastResolvedDeviceId
+        ? store.getLastResolvedDeviceId({ platform: "openclaw", accountId })
+        : null;
+    if (persistedDeviceId) {
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw reusing persisted resolved_device_id`);
+    }
     const client = createOpenclawClawlingClient(account, {
         ...(params.transport ? { transport: params.transport } : {}),
+        ...(persistedDeviceId ? { deviceIdOverride: persistedDeviceId } : {}),
         wsLifecycle: {
             onConnectFrameSent: (env) => {
                 lastConnectTraceId = typeof env.trace_id === "string" ? env.trace_id : "-";
@@ -627,6 +893,195 @@ export async function startOpenclawClawlingGateway(params) {
         },
     });
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client created`);
+    // §A.3/§A.4 — recompute the refresh-driven reconnect streak (depth + window).
+    // Returns the next depth/window to thread into the re-enter, and whether the
+    // cap is exceeded so the caller must NOT re-enter via refresh again.
+    const nextRefreshReconnectStreak = () => {
+        const now = Date.now();
+        const priorWindowStart = params.refreshReconnectWindowStartedAt ?? 0;
+        const withinWindow = priorWindowStart !== 0 && now - priorWindowStart < REFRESH_RECONNECT_WINDOW_MS;
+        const windowStartedAt = withinWindow ? priorWindowStart : now;
+        const depth = (withinWindow ? params.refreshReconnectDepth ?? 0 : 0) + 1;
+        return { depth, windowStartedAt, capped: depth > MAX_REFRESH_RECONNECTS };
+    };
+    // §B/§D — re-enter the gateway after a plain transport-backoff delay, with the
+    // CURRENT (unchanged) token and creds left untouched. Used when a reactive
+    // refresh is transient/skipped (§B: a transient refresh failure NEVER
+    // auto-logs-out and NEVER stops — keep retrying with the current token) and
+    // when the refresh-reconnect loop is capped (§A.4). Carries the refresh
+    // manager's latch + min-interval state so the guards keep bounding the loop.
+    const scheduleTransportBackoffReconnect = (reason) => {
+        if (abortSignal.aborted || autoLoggedOut || reconnectWithRefreshedToken)
+            return;
+        reconnectWithRefreshedToken = true; // suppress the auth-failed teardown path.
+        refreshManager.stop();
+        activeClients.delete(accountId);
+        finishCurrentConnection({
+            state: "disconnected",
+            closeCode: 1000,
+            closeReason: "transport backoff reconnect",
+        });
+        try {
+            client.close();
+        }
+        catch {
+            // best effort
+        }
+        const attempt = (params.refreshReconnectDepth ?? 0) + 1;
+        const delayMs = params.transportBackoffDelayMs ??
+            Math.min(TRANSPORT_BACKOFF_MAX_MS, TRANSPORT_BACKOFF_BASE_MS * 2 ** Math.max(0, attempt - 1));
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw reactive refresh ${reason}; backoff-reconnect with current token delayMs=${delayMs}`);
+        const managerState = refreshManager.exportState();
+        const streak = nextRefreshReconnectStreak();
+        const reEnter = () => {
+            if (abortSignal.aborted)
+                return;
+            void startOpenclawClawlingGateway({
+                ...params,
+                account: { ...params.account },
+                transportBackoffReconnect: true,
+                refreshReconnectDepth: streak.depth,
+                refreshReconnectWindowStartedAt: streak.windowStartedAt,
+                refreshManagerState: managerState,
+            });
+        };
+        const timer = params.backoffTimer ?? ((cb, ms) => void setTimeout(cb, ms));
+        timer(reEnter, delayMs);
+    };
+    // §A/§D — close the live WS and re-enter the gateway with the rotated token
+    // (a token only enters via a fresh `connect` envelope; it cannot be hot-swapped
+    // onto a live socket). Assumes a refresh ALREADY succeeded and swapped the
+    // in-memory token (proactive path), or is called by `runRefreshAndReconnect`
+    // after its own successful refresh (reactive path). Carries the refresh
+    // manager's latch + min-interval + reconnect-streak state across the re-enter.
+    const closeAndReconnectWithRefreshedToken = async (reason) => {
+        if (abortSignal.aborted || autoLoggedOut || reconnectWithRefreshedToken)
+            return;
+        reconnectWithRefreshedToken = true;
+        const managerState = refreshManager.exportState();
+        refreshManager.stop();
+        activeClients.delete(accountId);
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw token refreshed (${reason}); closing WS to reconnect with new token`);
+        finishCurrentConnection({
+            state: "disconnected",
+            closeCode: 1000,
+            closeReason: "token refresh",
+        });
+        try {
+            client.close();
+        }
+        catch {
+            // best effort
+        }
+        if (abortSignal.aborted)
+            return;
+        const streak = nextRefreshReconnectStreak();
+        // Re-enter with the rotated in-memory account; SQLite/config already hold
+        // the rotated pair (persisted before the swap). Reuse the same device id.
+        await startOpenclawClawlingGateway({
+            ...params,
+            account: {
+                ...params.account,
+                configured: true,
+                token: account.token,
+                userId: account.userId,
+                ownerUserId: account.ownerUserId,
+            },
+            refreshReconnectDepth: streak.depth,
+            refreshReconnectWindowStartedAt: streak.windowStartedAt,
+            refreshManagerState: managerState,
+        });
+    };
+    // Alias used by the proactive port (refresh already succeeded + swapped).
+    const runRefreshReconnect = closeAndReconnectWithRefreshedToken;
+    // §A/§B/§D — run a single-flight refresh and act on the outcome:
+    //  - success  → close the live WS + re-enter with the rotated token (§D).
+    //  - permanent→ the manager already auto-logged-out (§C); nothing more here.
+    //  - transient/skipped → §B: NEVER teardown. Backoff-reconnect with the CURRENT
+    //    token, creds + configured untouched, and keep retrying.
+    // Returns "handled" when it took ownership of the next connection lifecycle
+    // (reconnect scheduled / auto-logout), "fallthrough" when the caller should run
+    // its own path (only when aborted mid-flight).
+    const runRefreshAndReconnect = async (reason) => {
+        if (abortSignal.aborted || autoLoggedOut || reconnectWithRefreshedToken)
+            return "handled";
+        // §A.4 — if the refresh-driven reconnect loop is already capped, do not run
+        // another refresh; fall back to plain transport backoff with the current
+        // token so a rotate-then-reject server cannot loop forever with no backoff.
+        if ((params.refreshReconnectDepth ?? 0) >= MAX_REFRESH_RECONNECTS) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw refresh-reconnect loop capped (depth=${params.refreshReconnectDepth}); backoff-reconnect with current token`);
+            scheduleTransportBackoffReconnect("refresh-reconnect-capped");
+            return "handled";
+        }
+        const outcome = await refreshManager.refresh(reason);
+        if (abortSignal.aborted)
+            return "fallthrough";
+        if (autoLoggedOut)
+            return "handled"; // permanent → manager auto-logged-out.
+        if (outcome.kind === "success") {
+            await closeAndReconnectWithRefreshedToken(reason);
+            return "handled";
+        }
+        // §B — transient / skipped (in-flight / min-interval / rejected-latch /
+        // no-refresh-token): keep the WS in backoff with the CURRENT token; do NOT
+        // teardown. (no-refresh-token has no path to recover, but tearing down is
+        // wrong per §B; backoff keeps the supervisor alive without a refresh storm.)
+        scheduleTransportBackoffReconnect(`refresh-${outcome.kind}`);
+        return "handled";
+    };
+    // §A.2.1 — run an authenticated REST call; on a 401/403 (`ClawlingApiError`
+    // kind "auth") run the single-flight refresh and retry the call ONCE with a
+    // rebuilt api-client. Any other error propagates. Used to wrap the REST
+    // api-client so metadata/profile calls survive an expired access token
+    // without waiting for the WS handshake.
+    const isRestAuthError = (err) => err instanceof ClawlingApiError && err.kind === "auth";
+    const withRefresh = async (call) => {
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (!isRestAuthError(err) || abortSignal.aborted)
+                throw err;
+            const outcome = await refreshManager.refresh("rest-401");
+            if (outcome.kind !== "success")
+                throw err;
+            // The in-memory swap already invalidated the cached api-client; the next
+            // `call()` rebuilds it with the fresh token.
+            return await call();
+        }
+    };
+    // Activate the REST proxy's refresh wrapper now that the manager exists.
+    restWithRefresh = withRefresh;
+    // §A.2/§B — handle a WS hello-fail(auth) by gating a reactive refresh on the
+    // reason classification:
+    //  - token-rejected → refresh. Success reconnects with the fresh token;
+    //    permanent auto-logs-out; transient/skipped backoff-reconnects with the
+    //    CURRENT token (§B: a transient refresh failure NEVER auto-logs-out and
+    //    NEVER stops — `runRefreshAndReconnect` owns all three).
+    //  - generic + token near expiry → same refresh path.
+    //  - generic + token NOT near expiry → §A.2: transient backoff with the current
+    //    token (NO refresh, NO teardown). A backend outage emitting a generic
+    //    reason must not trigger a refresh storm OR a spurious logout.
+    //  - auth-unavailable never reaches here (the ws-client routes it as a
+    //    TransportError so its own backoff loop handles it).
+    const handleWsAuthFailure = async (reason) => {
+        if (abortSignal.aborted || reconnectWithRefreshedToken || autoLoggedOut)
+            return;
+        const klass = classifyHelloFailReason(reason);
+        const eligible = klass === "token-rejected" ||
+            (klass === "generic" && refreshManager.isNearExpiry(activatedAtMs));
+        if (eligible) {
+            // `runRefreshAndReconnect` is total: it either reconnects (success),
+            // auto-logs-out (permanent), or backoff-reconnects with the current token
+            // (transient/skipped). No teardown path remains for an eligible hello-fail.
+            await runRefreshAndReconnect("ws-hello-fail");
+            return;
+        }
+        // §A.2 / Finding 5 — generic + token NOT near expiry: keep the WS in
+        // transport backoff with the current token. Do NOT refresh and do NOT tear
+        // the account down (the old teardown wrongly flipped configured:false).
+        scheduleTransportBackoffReconnect("hello-fail-generic-not-near");
+    };
     setAlignedOutboundLogContext(client, wsLogContext);
     client.on("hello:ok", (env) => {
         const payload = env.payload && typeof env.payload === "object"
@@ -641,6 +1096,11 @@ export async function startOpenclawClawlingGateway(params) {
         send: () => { },
         context: wsLogContext,
     });
+    const notifySignalObserver = createNotifySignalObserver({
+        accountId,
+        log: (msg) => log?.info?.(msg),
+        context: wsLogContext,
+    });
     const logAuthFailure = (reason) => {
         if (authFailureLogged)
             return;
@@ -663,6 +1123,8 @@ export async function startOpenclawClawlingGateway(params) {
     client.on("state", ({ from, to }) => {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw state ${from} -> ${to}`);
         wsReady = to === "connected";
+        if (to === "connected")
+            wsReadyEverThisAttempt = true;
         if (to === "connecting") {
             reconnectTracker.connectStart();
             currentAttemptStartedAt = Date.now();
@@ -731,9 +1193,17 @@ export async function startOpenclawClawlingGateway(params) {
             }
             void refreshConversationCacheAfterReady();
             void dispatchActivationBootstrap();
+            // §A.1 — arm the proactive refresh timer from the live token's `exp`
+            // every time a connection becomes ready (re-armed after every refresh via
+            // the gateway re-enter).
+            refreshManager.armProactiveTimer(activatedAtMs);
         }
         else if (to === "disconnected") {
             reconnectTracker.markClosed();
+            // §A.1 — clear the proactive timer on disconnect; it re-arms on the next
+            // ready, or the gateway re-enter arms a fresh one.
+            if (!reconnectWithRefreshedToken)
+                refreshManager.disarmProactiveTimer();
         }
         const next = { ...getStatus(), ...mapClawlingStateToStatus(to) };
         setStatus(next);
@@ -863,21 +1333,48 @@ export async function startOpenclawClawlingGateway(params) {
     client.on("metadata:invalidated", (env) => {
         void handleMetadataInvalidation(env);
     });
+    client.on("notify:signal", (env) => {
+        // §9.4 reliable system notification. The plugin holds no friend/roster
+        // cache (friends are fetched on demand via REST tools), so there is nothing
+        // to invalidate — observe + dedup only. The live frame and its reliable
+        // inbox replay carry the same event_id and collapse to one observation.
+        notifySignalObserver.observe(env);
+    });
+    client.on("replay:done", (env) => {
+        // §11.5 terminal control frame: device replay drained, live delivery begins.
+        // Fires on every reconnect (even zero-backlog). Replayed messages are
+        // processed inline, so this is a logged boundary marker, not a gate.
+        log?.info?.(`[${accountId}] clawchat-plugin-openclaw replay.done trace=${env.trace_id}`);
+    });
     client.on("error", (err) => {
         const classified = classifyClawlingClientError(err);
         if (classified.kind === "auth") {
-            finishCurrentConnection({
-                state: "auth_failed",
-                error: lastHelloFailReason || classified.message,
-            });
-            logAuthFailure(classified.message);
-            setStatus({
-                ...getStatus(),
-                connected: false,
-                configured: false,
-                running: false,
-                lastError: classified.message,
-            });
+            // §A.2 — a WS hello-fail(auth) on a LIVE (already-connected) session.
+            // Attempt a gated reactive refresh before tearing the account down. The
+            // INITIAL-connect auth failure is owned by the `client.connect()` catch
+            // below (which runs the refresh/backoff/teardown decision and the recursive
+            // re-enter), so only react here once the session was previously ready —
+            // otherwise we'd double-handle and the error handler's teardown would race
+            // the catch's transient-backoff branch (wrongly flipping configured:false).
+            if (!reconnectWithRefreshedToken && !autoLoggedOut && wsReadyEverThisAttempt) {
+                void handleWsAuthFailure(lastHelloFailReason || classified.message);
+                return;
+            }
+            // Not-ready (initial connect): the `client.connect()` catch below owns the
+            // refresh/backoff/teardown DECISION and the status flip. Record the
+            // connection as auth_failed here (bookkeeping — the ws-client's own 4001
+            // close would otherwise finish it as a plain "disconnected") and log the
+            // auth failure, but do NOT flip status here: a transient refresh / generic
+            // backoff must leave configured untouched, and that decision lives in the
+            // catch.
+            if (!reconnectWithRefreshedToken && !autoLoggedOut) {
+                finishCurrentConnection({
+                    state: "auth_failed",
+                    error: lastHelloFailReason || classified.message,
+                });
+                logAuthFailure(classified.message);
+            }
+            return;
         }
         else if (classified.kind === "transport") {
             finishCurrentConnection({ state: "transport_error", error: classified.message });
@@ -1385,14 +1882,44 @@ export async function startOpenclawClawlingGateway(params) {
     }
     catch (err) {
         const classified = classifyClawlingClientError(err);
-        setStatus({
-            ...getStatus(),
-            connected: false,
-            configured: classified.kind !== "auth",
-            running: false,
-            lastError: classified.message,
-        });
         if (classified.kind === "auth") {
+            // §A.2/§B — initial-connect hello-fail(auth). Do NOT pre-flip
+            // configured:false here: a transient refresh must leave creds + configured
+            // untouched (§B). Branch on the refresh-eligibility classification first.
+            const klass = classifyHelloFailReason(lastHelloFailReason || classified.message);
+            const eligible = !reconnectWithRefreshedToken &&
+                !autoLoggedOut &&
+                !abortSignal.aborted &&
+                Boolean(latestRefreshToken) &&
+                (klass === "token-rejected" ||
+                    (klass === "generic" && refreshManager.isNearExpiry(activatedAtMs)));
+            if (eligible) {
+                // Total: success reconnects, permanent auto-logs-out, transient/skipped
+                // backoff-reconnects with the current token (creds + configured intact).
+                await runRefreshAndReconnect("ws-initial-connect-auth");
+                return;
+            }
+            // §A.2 / Finding 5 — generic + token NOT near expiry (and we have a refresh
+            // token but it isn't refresh-eligible): keep the WS in transport backoff
+            // with the current token instead of tearing the account down.
+            if (klass === "generic" &&
+                Boolean(latestRefreshToken) &&
+                !reconnectWithRefreshedToken &&
+                !autoLoggedOut &&
+                !abortSignal.aborted) {
+                scheduleTransportBackoffReconnect("initial-connect-generic-not-near");
+                return;
+            }
+            // Not refresh-eligible and no usable refresh token — fall back to the
+            // legacy auth-failed teardown so the gateway flips not-configured and (for
+            // a sqlite-sourced account) re-enters wait-for-activation.
+            setStatus({
+                ...getStatus(),
+                connected: false,
+                configured: false,
+                running: false,
+                lastError: classified.message,
+            });
             finishCurrentConnection({
                 state: "auth_failed",
                 error: lastHelloFailReason || classified.message,
@@ -1413,6 +1940,13 @@ export async function startOpenclawClawlingGateway(params) {
             }
             return;
         }
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            configured: true,
+            running: false,
+            lastError: classified.message,
+        });
         log?.error?.(`[${accountId}] clawchat-plugin-openclaw connect failed (${classified.kind}): ${classified.message}`);
         return;
     }
@@ -1429,6 +1963,8 @@ export async function startOpenclawClawlingGateway(params) {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime abort received; closing client`);
         activeClients.delete(accountId);
         closingForAbort = true;
+        // §A.1 — stop the proactive refresh timer on shutdown.
+        refreshManager.stop();
         groupCoalescer.cancelAll();
         finishCurrentConnection({
             state: "disconnected",