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

package/src/runtime.ts

@@ -16,6 +16,8 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient } from "./client.ts";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { ClawlingApiError } from "./api-types.ts";
+import { RefreshManager } from "./refresh-manager.ts";
+import type { OpenclawClawchatMutateConfigFile } from "./login.runtime.ts";
 import {
   CHANNEL_ID,
   effectiveOutputVisibility,
@@ -35,7 +37,7 @@ import {
   setAlignedOutboundLogContext,
 } from "./outbound.ts";
 import { formatWsLog } from "./ws-log.ts";
-import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.ts";
+import { createNotifySignalObserver, createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.ts";
 import {
   clawChatDbPathForStateDir,
   getClawChatStore,
@@ -77,6 +79,8 @@ type RuntimeConnectionStore = Pick<
     Pick<
       ClawChatStore,
       | "getActivationCredentials"
+      | "rotateActivationTokens"
+      | "clearActivationCredentials"
       | "insertMessage"
       | "claimMessageOnce"
       | "markMessageAcknowledged"
@@ -85,6 +89,7 @@ type RuntimeConnectionStore = Pick<
       | "releaseActivationBootstrapClaim"
       | "markActivationBootstrapSent"
       | "getActivationConversation"
+      | "getLastResolvedDeviceId"
     >
   >;
 
@@ -111,11 +116,44 @@ 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: unknown): value is Record<string, unknown> {
   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: string,
+): "token-rejected" | "auth-unavailable" | "generic" {
+  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: OpenClawConfig): string | null {
+  const channels = (cfg as { channels?: Record<string, unknown> }).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: OpenClawConfig, agentId: string): OpenClawConfig {
   const cfgRecord = cfg as Record<string, unknown>;
   const agents = isRecord(cfgRecord.agents) ? cfgRecord.agents : {};
@@ -339,7 +377,11 @@ function metadataScopesFromEnvelope(env: Envelope): string[] {
 }
 
 function shouldRefreshBehaviorForScopes(scopes: string[]): boolean {
-  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: string[]): boolean {
@@ -419,8 +461,56 @@ export interface StartGatewayParams {
   activationPollIntervalMs?: number;
   /** Test hook only. */
   rejectedActivationToken?: string;
+  /** Test hook only — fetch impl used by the refresh manager (`/v1/auth/refresh`). */
+  refreshFetchImpl?: typeof fetch;
+  /** Test hook only — setTimeout override for the refresh manager's proactive timer. */
+  refreshSetTimer?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout> | number;
+  /** Test hook only — clearTimeout override for the refresh manager's proactive timer. */
+  refreshClearTimer?: (handle: ReturnType<typeof setTimeout> | number) => void;
+  /** Test hook only — jitter override (ms) for the proactive timer. */
+  refreshJitter?: () => number;
+  /** Test hook only — config-file mutator used to persist rotated/blanked creds. */
+  mutateConfigFile?: OpenclawClawchatMutateConfigFile;
+  /** Internal — set when the current attempt is a refresh-driven reconnect. */
+  refreshReconnectDepth?: number;
+  /**
+   * Internal — epoch-ms at which the current refresh-driven reconnect streak
+   * began. Used with `refreshReconnectDepth` to bound a rotate-then-reject loop
+   * (§A.3/§A.4): once depth exceeds the cap inside the window we stop re-entering
+   * via refresh and fall back to plain transport backoff with the current token.
+   */
+  refreshReconnectWindowStartedAt?: number;
+  /**
+   * Internal — the refresh manager's single-flight latch + min-interval state,
+   * carried across gateway re-enters so the §A.3 guards (rejected-token latch,
+   * min-interval floor) actually constrain a cross-reconnect refresh loop instead
+   * of resetting on every fresh `RefreshManager`.
+   */
+  refreshManagerState?: { rejectedToken: string | null; lastAttemptAt: number };
+  /**
+   * Internal — set when the current attempt is a plain transport-backoff
+   * re-enter (transient/skipped reactive refresh). Carries the current (unchanged)
+   * token so creds stay untouched; the auth-failure teardown is suppressed.
+   */
+  transportBackoffReconnect?: boolean;
+  /** Test hook only — setTimeout override for the transport-backoff delay. */
+  backoffTimer?: (cb: () => void, ms: number) => void;
+  /** Test hook only — fixed transport-backoff delay (ms) for re-enter. */
+  transportBackoffDelayMs?: number;
 }
 
+/**
+ * §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: StartGatewayParams,
   runtime: PluginRuntime,
@@ -563,15 +653,95 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   });
   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: number | null =
+    activationAccount.source === "sqlite" && store?.getActivationCredentials
+      ? store.getActivationCredentials({ platform: "openclaw", accountId })?.activatedAt ?? null
+      : null;
   let conversationApiClient: ReturnType<typeof createOpenclawClawlingApiClient> | undefined;
-  const getConversationApiClient = () => {
-    conversationApiClient ??= createOpenclawClawlingApiClient({
+  const buildConversationApiClient = (): ReturnType<typeof createOpenclawClawlingApiClient> =>
+    createOpenclawClawlingApiClient({
       baseUrl: account.baseUrl,
       mediaBaseUrl: account.mediaBaseUrl,
       token: account.token,
       userId: account.userId,
     });
-    return conversationApiClient;
+  // §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: (<T>(call: () => Promise<T>) => Promise<T>) | null = 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 = (): ReturnType<typeof createOpenclawClawlingApiClient> => {
+    return new Proxy({} as ReturnType<typeof createOpenclawClawlingApiClient>, {
+      get: (_target, prop) => {
+        return (...args: unknown[]) => {
+          const invoke = () => {
+            conversationApiClient ??= buildConversationApiClient();
+            const fn = (conversationApiClient as unknown as Record<string, unknown>)[
+              prop as string
+            ];
+            if (typeof fn !== "function") {
+              throw new TypeError(`clawchat api-client has no method ${String(prop)}`);
+            }
+            return (fn as (...a: unknown[]) => unknown).apply(conversationApiClient, args);
+          };
+          return restWithRefresh
+            ? restWithRefresh(() => Promise.resolve(invoke()) as Promise<unknown>)
+            : invoke();
+        };
+      },
+    });
+  };
+  // Rebuilt after every in-memory token swap so REST calls use the fresh token.
+  const invalidateConversationApiClient = () => {
+    conversationApiClient = undefined;
+  };
+
+  const resolveMutateConfigFile = (): OpenclawClawchatMutateConfigFile | undefined => {
+    if (params.mutateConfigFile) return params.mutateConfigFile;
+    const runtimeConfig = runtime.config as unknown as {
+      mutateConfigFile?: OpenclawClawchatMutateConfigFile;
+    };
+    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: { accessToken: string; refreshToken: string } | null,
+  ): Promise<void> => {
+    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 as { channels?: Record<string, unknown> }).channels ?? {}) as Record<
+          string,
+          unknown
+        >;
+        const existing = (channels[CHANNEL_ID] ?? {}) as Record<string, unknown>;
+        const nextSection: Record<string, unknown> = {
+          ...existing,
+          token: tokens ? tokens.accessToken : "",
+          refreshToken: tokens ? tokens.refreshToken : "",
+        };
+        Object.assign(draft, {
+          ...draft,
+          channels: { ...channels, [CHANNEL_ID]: nextSection },
+        });
+      },
+    });
   };
 
   let lastHelloFailTraceId = "-";
@@ -583,6 +753,141 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   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: { code: number; message: string }): Promise<void> => {
+    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 = (): void => {
+    log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${CLAWCHAT_TOKEN_EXPIRED_MESSAGE}`);
+    try {
+      const notify = (runtime as unknown as {
+        notifications?: { notify?: (input: { level?: string; message: string }) => void };
+      }).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: string | null =
+    (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: number | null = null;
   let currentConnectionFinished = false;
   const reconnectTracker = createReconnectTracker({
@@ -721,7 +1026,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     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 } : {}),
@@ -792,8 +1100,41 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       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 : "-";
@@ -823,6 +1164,202 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   });
   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 = (): {
+    depth: number;
+    windowStartedAt: number;
+    capped: boolean;
+  } => {
+    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: string): void => {
+    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: string): Promise<void> => {
+    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: string): Promise<"handled" | "fallthrough"> => {
+    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: unknown): boolean =>
+    err instanceof ClawlingApiError && err.kind === "auth";
+  const withRefresh = async <T>(call: () => Promise<T>): Promise<T> => {
+    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: string): Promise<void> => {
+    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: Envelope) => {
     const payload = env.payload && typeof env.payload === "object"
@@ -837,6 +1374,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     send: () => {},
     context: wsLogContext,
   });
+  const notifySignalObserver = createNotifySignalObserver({
+    accountId,
+    log: (msg) => log?.info?.(msg),
+    context: wsLogContext,
+  });
   const logAuthFailure = (reason: string) => {
     if (authFailureLogged) return;
     authFailureLogged = true;
@@ -861,6 +1403,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   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();
@@ -931,8 +1474,15 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }
       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 as ClawlingState) };
     setStatus(next);
@@ -1076,21 +1626,50 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     void handleMetadataInvalidation(env);
   });
 
+  client.on("notify:signal", (env: Envelope) => {
+    // §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: Envelope) => {
+    // §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: unknown) => {
     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 });
       const current = wsLogContext();
@@ -1672,14 +2251,47 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client.connect() resolved`);
   } 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,
@@ -1700,6 +2312,13 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }
       return;
     }
+    setStatus({
+      ...getStatus(),
+      connected: false,
+      configured: true,
+      running: false,
+      lastError: classified.message,
+    });
     log?.error?.(
       `[${accountId}] clawchat-plugin-openclaw connect failed (${classified.kind}): ${classified.message}`,
     );
@@ -1719,6 +2338,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     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",