@clawling/clawchat-plugin-openclaw 2026.10.11-3 → 2026.10.13-1

package/dist/src/api-client.js

@@ -251,6 +251,7 @@ export function createOpenclawClawlingApiClient(opts) {
                     ? env.message
                     : "";
             if (code !== 0) {
+                // Business-code 401 is an API error, not HTTP auth expiry; do not refresh.
                 throw new ClawlingApiError("api", msg || `code=${code}`, {
                     code,
                     status: res.status,

package/dist/src/refresh-manager.js

@@ -1,4 +1,9 @@
+import { createHash } from "node:crypto";
 import { authRefresh, CODE_INVALID_REFRESH, decodeJwtExp, } from "./api-client.js";
+/** Fingerprint only: revoked refresh credentials must never enter marker storage. */
+export function fingerprintRefreshToken(token) {
+    return createHash("sha256").update(token.trim()).digest("hex");
+}
 /**
  * §A–§D — ClawChat token refresh + auto-logout orchestration for the OpenClaw
  * plugin.
@@ -70,12 +75,9 @@ export class RefreshManager {
     inFlight = null;
     /** §A.3 — the access token a refresh was last attempted for. */
     rejectedToken = null;
-    /**
-     * §B race — the refresh token we last successfully rotated AWAY from (now
-     * consumed server-side). A subsequent `code:10003` for this exact token is a
-     * consumed-rotation race, NOT a revocation, so it must not auto-logout.
-     */
+    /** Consumed-token history is diagnostic; a live successor is required to recover. */
     lastRotatedFromToken = null;
+    consecutiveRaceDowngrades = 0;
     /** §A.3 — epoch-ms of the last refresh attempt (any token). */
     lastAttemptAt = 0;
     proactiveTimer = null;
@@ -135,10 +137,12 @@ export class RefreshManager {
             result = await authRefresh({ baseUrl: this.ports.baseUrl, ...(this.ports.fetchImpl ? { fetchImpl: this.ports.fetchImpl } : {}) }, { refreshToken, deviceId: this.ports.deviceId });
         }
         catch (err) {
+            this.consecutiveRaceDowngrades = 0;
             const message = err instanceof Error ? err.message : String(err);
             return { kind: "transient", message };
         }
         if (result.kind === "success") {
+            this.consecutiveRaceDowngrades = 0;
             // §0 rotation hazard — persist FIRST, swap SECOND. If persistence REJECTS
             // (a store/config write failed), DO NOT swap the in-memory token: a
             // sqlite-sourced agent must not keep a now-dead refresh token in its row
@@ -163,8 +167,7 @@ export class RefreshManager {
                 accessToken: result.accessToken,
                 refreshToken: result.refreshToken,
             });
-            // §B race — record the now-consumed refresh token so a later `10003` for it
-            // is recognized as a rotation race rather than a revocation.
+            // Keep rotation history for inspection; it never overrides the live-token check.
             this.lastRotatedFromToken = refreshToken;
             // Clear the latch; the access token has actually changed.
             this.rejectedToken = null;
@@ -172,31 +175,27 @@ export class RefreshManager {
             return { kind: "success", accessToken: result.accessToken, refreshToken: result.refreshToken };
         }
         if (result.kind === "permanent") {
-            // §B race — a `code:10003` is also returned for a refresh token already
-            // CONSUMED by a prior successful rotation (once the backend grace window
-            // no longer covers it). Before auto-logging-out
-            // (which wipes credentials and bricks the agent), distinguish that race
-            // from a genuine revocation. It is a race when EITHER the submitted token
-            // is one we already rotated away from, OR the live store refresh token has
-            // moved on since we read it (another worker rotated underneath us). In
-            // either case the credential chain is still alive — report transient (no
-            // latch, no logout) so the next attempt proceeds with the live token. A
-            // `code:400` (client bug) is never a race.
+            // A consumed-token race is recoverable only with a real live successor.
+            // Bound repeated downgrades, including across gateway re-enters.
             if (result.code === CODE_INVALID_REFRESH) {
                 const liveRefresh = this.ports.getRefreshToken();
-                const rotatedByUs = this.lastRotatedFromToken !== null && refreshToken === this.lastRotatedFromToken;
-                const rotatedUnderneath = !!liveRefresh && liveRefresh.trim().length > 0 && liveRefresh !== refreshToken;
-                if (rotatedByUs || rotatedUnderneath) {
-                    this.ports.log?.info?.(`clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race (rotatedByUs=${rotatedByUs} rotatedUnderneath=${rotatedUnderneath}); recovering with live token`);
+                const hasSuccessor = !!liveRefresh?.trim() && liveRefresh !== refreshToken;
+                if (hasSuccessor && this.consecutiveRaceDowngrades < 2) {
+                    this.consecutiveRaceDowngrades += 1;
+                    this.ports.log?.info?.("clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race; recovering with live token");
                     return { kind: "transient", message: "refresh token already rotated (race); retrying with current token" };
                 }
             }
             // §A.3 — latch the dead token so reconnect storms don't re-fire refresh.
             this.rejectedToken = accessToken;
             this.ports.log?.error?.(`clawchat-plugin-openclaw refresh permanent failure code=${result.code}: ${result.message}`);
-            await this.ports.onPermanentFailure({ code: result.code, message: result.message });
+            await this.ports.onPermanentFailure({
+                code: result.code,
+                message: result.message,
+            }, { fingerprint: fingerprintRefreshToken(refreshToken), revokedAt: this.now() });
             return { kind: "permanent", code: result.code, message: result.message };
         }
+        this.consecutiveRaceDowngrades = 0;
         // Transient — never auto-logout; the old refresh token is still valid.
         this.ports.log?.info?.(`clawchat-plugin-openclaw refresh transient failure: ${result.message}`);
         return { kind: "transient", message: result.message };
@@ -362,6 +361,7 @@ export class RefreshManager {
             rejectedToken: this.rejectedToken,
             lastAttemptAt: this.lastAttemptAt,
             lastRotatedFromToken: this.lastRotatedFromToken,
+            consecutiveRaceDowngrades: this.consecutiveRaceDowngrades,
         };
     }
     /** §A.3/§A.4 — restore guard state from a prior manager (see `exportState`). */
@@ -369,6 +369,7 @@ export class RefreshManager {
         this.rejectedToken = state.rejectedToken;
         this.lastAttemptAt = state.lastAttemptAt;
         this.lastRotatedFromToken = state.lastRotatedFromToken ?? null;
+        this.consecutiveRaceDowngrades = state.consecutiveRaceDowngrades ?? 0;
     }
 }
 function decodeJwtIat(token) {

package/dist/src/runtime.js

@@ -14,7 +14,7 @@ import { readOnboardingReport } from "./onboarding-report.js";
 import { ensureLivewareCli, livewareCliHomeDir, livewareSampleRootDir, resolveLivewarePath, } from "./liveware-cli.js";
 import { LivewareSampleSupervisor, } from "./liveware-sample.js";
 import { ClawlingApiError } from "./api-types.js";
-import { RefreshManager } from "./refresh-manager.js";
+import { RefreshManager, fingerprintRefreshToken } from "./refresh-manager.js";
 import { RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 import { runOpenclawClawlingLogin, } from "./login.runtime.js";
 import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effectiveGroupMode, hasOpenclawClawlingConnectCredentials, normalizeOpenclawClawlingAccountId, readOpenclawClawlingAccountSection, resolveOpenclawClawlingAccount, CLAWCHAT_REFRESH_TOKEN_ENV, } from "./config.js";
@@ -157,19 +157,25 @@ export function classifyHelloFailReason(reason) {
  * carries no `token` of its own (i.e. the access token itself came from
  * `CLAWCHAT_TOKEN`) — an env-provisioned pair can rotate, while a login-written
  * token is never paired with a stray refresh token left in the environment.
+ * A revoked marker also excludes a matching refresh fingerprint from either source.
  */
-function readConfigRefreshToken(cfg, accountId, env = process.env) {
+function readConfigRefreshToken(cfg, accountId, revokedMarker, env = process.env) {
     const section = readOpenclawClawlingAccountSection(cfg, accountId);
     const refreshToken = section.refreshToken;
+    const usable = (token) => {
+        const value = typeof token === "string" ? token.trim() : "";
+        return value && (!revokedMarker || fingerprintRefreshToken(value) !== revokedMarker.fingerprint)
+            ? value : null;
+    };
     if (typeof refreshToken === "string" && refreshToken.trim())
-        return refreshToken.trim();
+        return usable(refreshToken);
     if (normalizeOpenclawClawlingAccountId(accountId) !== DEFAULT_ACCOUNT_ID)
         return null;
     const configToken = section.token;
     if (typeof configToken === "string" && configToken.trim())
         return null;
     const envRefreshToken = env[CLAWCHAT_REFRESH_TOKEN_ENV];
-    return typeof envRefreshToken === "string" && envRefreshToken.trim() ? envRefreshToken.trim() : null;
+    return usable(envRefreshToken);
 }
 function withFullVerboseDispatchConfig(cfg, agentId) {
     const cfgRecord = cfg;
@@ -657,13 +663,18 @@ function waitForActivationPoll(abortSignal, ms) {
 async function waitForActivationCredentials(params) {
     const { abortSignal, getStatus, setStatus, store, log } = params;
     const accountId = params.account.accountId;
+    const revoked = params.revokedRefreshMarker;
+    const usable = (credentials) => credentials.accessToken !== params.rejectedActivationToken &&
+        (!revoked || (!!credentials.refreshToken &&
+            fingerprintRefreshToken(credentials.refreshToken) !== revoked.fingerprint));
     // SQLite-first: activation and token rotation persist to the activations
     // row, so a complete row is the durable credential source of truth even
     // when channel config/env also carries credentials. Config/env credentials
-    // only bootstrap the no-row case (the caller seeds a row from them).
+    // bootstrap the no-row case, or replace a revoked pair with a different
+    // refresh fingerprint (the caller seeds a row from the adopted pair).
     if (store?.getActivationCredentials) {
         const stored = store.getActivationCredentials({ platform: "openclaw", accountId });
-        if (stored && stored.accessToken !== params.rejectedActivationToken) {
+        if (stored && usable(stored)) {
             log?.info?.(`[${accountId}] clawchat-plugin-openclaw loaded activation credentials from sqlite`);
             return {
                 source: "sqlite",
@@ -677,10 +688,20 @@ async function waitForActivationCredentials(params) {
             };
         }
     }
-    if (accountHasConnectCredentials(params.account)) {
-        return { account: params.account, source: "configured" };
+    const configuredCredentials = (account) => {
+        const refreshToken = readConfigRefreshToken(params.cfg, accountId, revoked);
+        return accountHasConnectCredentials(account) && usable({ accessToken: account.token, refreshToken })
+            ? { account, source: "configured" } : null;
+    };
+    const configured = configuredCredentials(params.account);
+    if (configured)
+        return configured;
+    if (revoked) {
+        log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${CLAWCHAT_TOKEN_EXPIRED_MESSAGE}`);
+        setStatus({ ...getStatus(), connected: false, configured: false, running: false,
+            lastError: CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR });
     }
-    if (!store?.getActivationCredentials) {
+    if (!revoked && !store?.getActivationCredentials) {
         const message = "Clawling Chat token is missing and activation database is unavailable";
         log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${message}`);
         setStatus({
@@ -693,26 +714,17 @@ async function waitForActivationCredentials(params) {
         return null;
     }
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw waiting for activation credentials in sqlite`);
-    setStatus({
-        ...getStatus(),
-        connected: false,
-        configured: true,
-        running: true,
-        lastError: "waiting for ClawChat activation",
-    });
-    while (!abortSignal.aborted) {
-        const credentials = store.getActivationCredentials({
-            platform: "openclaw",
-            accountId,
+    if (!revoked)
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            configured: true,
+            running: true,
+            lastError: "waiting for ClawChat activation",
         });
-        if (credentials) {
-            if (credentials.accessToken === params.rejectedActivationToken) {
-                log?.debug?.(`[${accountId}] clawchat-plugin-openclaw activation credential poll heartbeat status=rejected_token_unchanged intervalMs=${params.pollIntervalMs}`);
-                const shouldContinue = await waitForActivationPoll(abortSignal, params.pollIntervalMs);
-                if (!shouldContinue)
-                    break;
-                continue;
-            }
+    while (!abortSignal.aborted) {
+        const credentials = store?.getActivationCredentials?.({ platform: "openclaw", accountId });
+        if (credentials && usable(credentials)) {
             log?.info?.(`[${accountId}] clawchat-plugin-openclaw loaded activation credentials from sqlite`);
             return {
                 source: "sqlite",
@@ -725,7 +737,14 @@ async function waitForActivationCredentials(params) {
                 },
             };
         }
-        log?.debug?.(`[${accountId}] clawchat-plugin-openclaw activation credential poll heartbeat status=waiting intervalMs=${params.pollIntervalMs}`);
+        if (revoked) {
+            // Re-read env credentials while parked so a new pair can recover without
+            // another gateway invocation. Config credentials use the supplied snapshot.
+            const replacement = configuredCredentials(resolveOpenclawClawlingAccount(params.cfg, accountId));
+            if (replacement)
+                return replacement;
+        }
+        log?.debug?.(`[${accountId}] clawchat-plugin-openclaw activation credential poll heartbeat status=${credentials ? "rejected_token_unchanged" : "waiting"} intervalMs=${params.pollIntervalMs}`);
         const shouldContinue = await waitForActivationPoll(abortSignal, params.pollIntervalMs);
         if (!shouldContinue)
             break;
@@ -741,6 +760,18 @@ async function waitForActivationCredentials(params) {
 let warnedBelowHostFloor = false;
 let loggedHostToolSearch = false;
 export async function startOpenclawClawlingGateway(params) {
+    // Every exit, including an interrupted connect or abort during logout, must
+    // wait for the one re-pair lifecycle this invocation started: settling the
+    // host's startAccount task early would make the host restart the channel.
+    const lifecycle = {};
+    try {
+        await runOpenclawClawlingGateway(params, lifecycle);
+    }
+    finally {
+        await lifecycle.rePairWait;
+    }
+}
+async function runOpenclawClawlingGateway(params, lifecycle) {
     const { cfg, abortSignal, setStatus, getStatus, log } = params;
     let account = params.account;
     // Obtain PluginRuntime from the stored runtime set via setOpenclawClawlingRuntime.
@@ -801,7 +832,10 @@ export async function startOpenclawClawlingGateway(params) {
             log,
         });
     }
+    const revokedRefreshMarker = params.revokedRefreshMarker ??
+        store?.getRevokedRefreshMarker?.({ platform: "openclaw", accountId });
     const activationAccount = await waitForActivationCredentials({
+        cfg,
         account,
         abortSignal,
         getStatus,
@@ -810,10 +844,16 @@ export async function startOpenclawClawlingGateway(params) {
         log,
         pollIntervalMs: params.activationPollIntervalMs ?? ACTIVATION_CREDENTIAL_POLL_INTERVAL_MS,
         rejectedActivationToken: params.rejectedActivationToken,
+        revokedRefreshMarker,
     });
     if (!activationAccount)
         return;
     account = activationAccount.account;
+    // Reset in-memory refresh guards only after adopting a different pair.
+    if (revokedRefreshMarker) {
+        params = { ...params, revokedRefreshMarker: undefined, refreshTokenOverride: undefined,
+            refreshManagerState: undefined, rejectedActivationToken: undefined };
+    }
     // Config/env bootstrap seeding: converge on SQLite as the single durable
     // credential store, so token rotation always has a row to update and the
     // next startup resolves SQLite-first to the same credentials.
@@ -825,7 +865,7 @@ export async function startOpenclawClawlingGateway(params) {
                 userId: account.userId,
                 ownerUserId: account.ownerUserId,
                 accessToken: account.token,
-                refreshToken: readConfigRefreshToken(cfg, accountId),
+                refreshToken: readConfigRefreshToken(cfg, accountId, revokedRefreshMarker),
                 loginMethod: "config-seed",
                 deviceId: CHANNEL_ID,
             });
@@ -834,6 +874,11 @@ export async function startOpenclawClawlingGateway(params) {
             log?.error?.(`[${accountId}] clawchat-plugin-openclaw sqlite credential seed failed; continuing with config credentials: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    if (revokedRefreshMarker && store) {
+        if (store.clearRevokedRefreshMarker?.({ platform: "openclaw", accountId }) !== true) {
+            log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear sqlite revoked marker after activation`);
+        }
+    }
     // Paired: link the report row via the authenticated endpoint, reusing the
     // SAME frozen device_id so the backend upserts the existing unpaired row.
     void reportPluginVersionSafe({
@@ -1023,7 +1068,7 @@ export async function startOpenclawClawlingGateway(params) {
         const mutateConfigFile = resolveMutateConfigFile();
         if (!mutateConfigFile) {
             log?.error?.(`[${accountId}] clawchat-plugin-openclaw config persistence unavailable; cannot ${tokens ? "rotate" : "clear"} tokens in config`);
-            return;
+            return false;
         }
         await mutateConfigFile({
             afterWrite: { mode: "none", reason: "clawchat-plugin-openclaw token refresh" },
@@ -1034,6 +1079,7 @@ export async function startOpenclawClawlingGateway(params) {
                 }));
             },
         });
+        return true;
     };
     let lastHelloFailTraceId = "-";
     let lastHelloFailReason = "";
@@ -1054,6 +1100,8 @@ export async function startOpenclawClawlingGateway(params) {
     let reconnectWithRefreshedToken = false;
     // §C — set once auto-logout has fired so we don't double-emit or reconnect.
     let autoLoggedOut = false;
+    let refreshClient;
+    let autoLogoutCleanup;
     // §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`.
@@ -1063,33 +1111,66 @@ export async function startOpenclawClawlingGateway(params) {
     // §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;
+    const performAutoLogout = (info, marker) => {
+        if (autoLogoutCleanup)
+            return autoLogoutCleanup;
         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.
+        refreshManager.stop();
+        activeClients.delete(accountId);
         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)}`);
+            refreshClient?.close();
         }
-        // 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();
+        catch { /* Best effort shutdown. */ }
+        // Write the marker independently BEFORE clearing, so a failed clear cannot
+        // resurrect this rejected credential at the next process start.
+        autoLogoutCleanup = (async () => {
+            const markerInput = { platform: "openclaw", accountId, ...marker };
+            try {
+                if (store?.setRevokedRefreshMarker?.(markerInput) !== true) {
+                    log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to persist sqlite revoked refresh marker`);
+                }
+            }
+            catch {
+                log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to persist sqlite revoked refresh marker`);
+            }
+            try {
+                if (store?.clearActivationCredentials?.({ platform: "openclaw", accountId }) !== true) {
+                    log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear sqlite credentials on auto-logout`);
+                }
+            }
+            catch {
+                log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear sqlite credentials on auto-logout`);
+            }
+            try {
+                if (!await persistConfigTokens(null))
+                    throw new Error("config mutation unavailable");
+            }
+            catch {
+                log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear config credentials on auto-logout`);
+            }
+            // 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();
+        })();
+        // Assign the lifetime before yielding, including when config clearing is
+        // still pending and closing the old socket interrupts client.connect().
+        lifecycle.rePairWait = autoLogoutCleanup.then(() => startOpenclawClawlingGateway({
+            ...params, boundaryWarningIssued: true,
+            account: { ...account, configured: false, token: "" },
+            revokedRefreshMarker: marker, refreshTokenOverride: undefined,
+            refreshManagerState: undefined, rejectedActivationToken: undefined,
+            refreshReconnectDepth: undefined, refreshReconnectWindowStartedAt: undefined,
+        }));
+        return autoLogoutCleanup;
     };
     // §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
@@ -1120,7 +1201,7 @@ export async function startOpenclawClawlingGateway(params) {
         (activationAccount.source === "sqlite" && store?.getActivationCredentials
             ? store.getActivationCredentials({ platform: "openclaw", accountId })?.refreshToken
             : null) ??
-        readConfigRefreshToken(cfg, accountId);
+        readConfigRefreshToken(cfg, accountId, revokedRefreshMarker);
     const refreshManager = new RefreshManager({
         baseUrl: account.baseUrl,
         deviceId: refreshDeviceId,
@@ -1180,7 +1261,9 @@ export async function startOpenclawClawlingGateway(params) {
             // No SQLite store available — channel config is the only durable
             // store, so its write failure must reject and keep the refresh
             // transient (pre-existing behavior for store-less test transports).
-            await persistConfigTokens(tokens);
+            if (!await persistConfigTokens(tokens)) {
+                throw new Error("clawchat-plugin-openclaw config persistence unavailable");
+            }
         },
         swapInMemoryTokens: (tokens) => {
             account = { ...account, token: tokens.accessToken, configured: true };
@@ -1436,7 +1519,8 @@ export async function startOpenclawClawlingGateway(params) {
         if (abortSignal.aborted)
             return;
         if (startupOutcome.kind === "permanent") {
-            // Auto-logout already performed by the manager's onPermanentFailure.
+            // Wait for re-pair or abort rather than settling the host channel task.
+            await lifecycle.rePairWait;
             return;
         }
         // success swaps the in-memory token in place; transient/skipped just connect
@@ -1479,6 +1563,7 @@ export async function startOpenclawClawlingGateway(params) {
             },
         },
     });
+    refreshClient = client;
     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
@@ -1611,8 +1696,10 @@ export async function startOpenclawClawlingGateway(params) {
         const outcome = await refreshManager.refresh(reason);
         if (abortSignal.aborted)
             return "fallthrough";
-        if (autoLoggedOut)
-            return "handled"; // permanent → manager auto-logged-out.
+        if (autoLoggedOut) {
+            await lifecycle.rePairWait;
+            return "handled";
+        }
         if (outcome.kind === "success") {
             await closeAndReconnectWithRefreshedToken(reason);
             return "handled";
@@ -3264,8 +3351,9 @@ export async function startOpenclawClawlingGateway(params) {
             // return on abort, but only AFTER it has already taken the idempotency claim
             // (`claimInboundTurn` runs BEFORE the gate wait there, so the frame is durably
             // persisted before the interruptible wait — required by legacy advance-on-
-            // write delivery, where a frame written before a disconnect is not re-delivered
-            // on reconnect; see docs/client-integration.md §11.7). So even an ingest-time
+            // write delivery, where a frame written before a disconnect is not reliably
+            // re-delivered on reconnect (legacy may lose OR replay; a replay is deduped by
+            // the claim); see docs/client-integration.md §11.7). So even an ingest-time
             // abort keeps the frame; it just skips dispatch. Here at FLUSH the batch was
             // likewise already claimed at ingest AND `flush()` has already removed it from
             // the coalescer's pending set. An abort early-return would therefore silently
@@ -3386,11 +3474,14 @@ export async function startOpenclawClawlingGateway(params) {
             // can interrupt. This client does NOT advertise `reliable_delivery`
             // (src/ws-client.ts), so under legacy delivery the server's replay cursor
             // advances on socket-WRITE (docs/client-integration.md §11.7): a frame
-            // already written before a disconnect is NOT re-delivered on reconnect.
+            // already written before a disconnect is NOT reliably re-delivered on
+            // reconnect. Legacy is not at-most-once either — a multi-replica server
+            // (relayed frames do not advance the cursor) or a failed cursor write can
+            // replay frames already received — and the claim below dedupes those.
             // `claimMessageOnce` is the ONLY durability an inbound has, and the store
             // never reprocesses undispatched inbounds. So if we claimed only AFTER the
-            // wait, a shutdown-mid-wait would leave the frame neither persisted NOR
-            // replayed — permanently lost. Claiming first makes it durable; the abort
+            // wait, a shutdown-mid-wait would leave the frame unpersisted with no
+            // guaranteed replay — lost. Claiming first makes it durable; the abort
             // check below then returns without dispatching, but the frame is kept.
             // `claimInboundTurn` is INSERT OR IGNORE, so a genuine duplicate (same
             // message_id) is still deduped here exactly once. The claim fails CLOSED:
@@ -3689,6 +3780,10 @@ export async function startOpenclawClawlingGateway(params) {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client.connect() resolved`);
     }
     catch (err) {
+        if (autoLoggedOut) {
+            await lifecycle.rePairWait;
+            return;
+        }
         const classified = classifyClawlingClientError(err);
         if (classified.kind === "auth") {
             // §A.2/§B — initial-connect hello-fail(auth). Do NOT pre-flip
@@ -3759,6 +3854,10 @@ export async function startOpenclawClawlingGateway(params) {
         log?.error?.(`[${accountId}] clawchat-plugin-openclaw connect failed (${classified.kind}): ${classified.message}`);
         return;
     }
+    if (autoLoggedOut) {
+        await lifecycle.rePairWait;
+        return;
+    }
     activeClients.set(accountId, client);
     // Text "@name" autolinking on outbound group sends reads the same cached
     // roster (participant ids + nicknames) the group prompt shows the model.

package/dist/src/storage.js

@@ -208,6 +208,19 @@ CREATE INDEX IF NOT EXISTS idx_clawchat_messages_protocol_message_id_nocase
         sql: `
 CREATE INDEX IF NOT EXISTS idx_clawchat_messages_chat_id_nocase
   ON clawchat_messages(chat_id COLLATE NOCASE);
+`,
+    },
+    {
+        version: 13,
+        name: "revoked_refresh_tokens",
+        sql: `
+CREATE TABLE IF NOT EXISTS revoked_refresh_tokens (
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  revoked_at INTEGER NOT NULL,
+  PRIMARY KEY (platform, account_id)
+);
 `,
     },
 ];
@@ -340,6 +353,31 @@ export class ClawChatStore {
             return result.changes > 0;
         });
     }
+    setRevokedRefreshMarker(input) {
+        return this.write(() => {
+            this.requireDb().prepare(`INSERT INTO revoked_refresh_tokens
+        (platform, account_id, fingerprint, revoked_at) VALUES (?, ?, ?, ?)
+        ON CONFLICT(platform, account_id) DO UPDATE SET
+        fingerprint = excluded.fingerprint, revoked_at = excluded.revoked_at`)
+                .run(input.platform, input.accountId, input.fingerprint, input.revokedAt);
+            return true;
+        });
+    }
+    getRevokedRefreshMarker(input) {
+        return this.read(() => {
+            const row = this.requireDb().prepare(`SELECT fingerprint, revoked_at AS revokedAt
+        FROM revoked_refresh_tokens WHERE platform = ? AND account_id = ?`)
+                .get(input.platform, input.accountId);
+            return row ?? null;
+        }) ?? null;
+    }
+    clearRevokedRefreshMarker(input) {
+        return this.write(() => {
+            this.requireDb().prepare(`DELETE FROM revoked_refresh_tokens WHERE platform = ? AND account_id = ?`)
+                .run(input.platform, input.accountId);
+            return true;
+        });
+    }
     getActivationCredentials(input) {
         return this.read(() => {
             const row = this.requireDb()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.11-3",
+  "version": "2026.10.13-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/api-client.ts

@@ -488,6 +488,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
             ? env.message
             : "";
       if (code !== 0) {
+        // Business-code 401 is an API error, not HTTP auth expiry; do not refresh.
         throw new ClawlingApiError("api", msg || `code=${code}`, {
           code,
           status: res.status,

package/src/refresh-manager.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import {
   authRefresh,
   CODE_INVALID_REFRESH,
@@ -5,6 +7,13 @@ import {
   type AuthRefreshResult,
 } from "./api-client.ts";
 
+export type RevokedRefreshMarker = { fingerprint: string; revokedAt: number };
+
+/** Fingerprint only: revoked refresh credentials must never enter marker storage. */
+export function fingerprintRefreshToken(token: string): string {
+  return createHash("sha256").update(token.trim()).digest("hex");
+}
+
 /**
  * §A–§D — ClawChat token refresh + auto-logout orchestration for the OpenClaw
  * plugin.
@@ -77,7 +86,7 @@ export interface RefreshManagerPorts {
   /** Swap the in-memory access+refresh token AFTER persistence (§0). */
   swapInMemoryTokens: (tokens: { accessToken: string; refreshToken: string }) => void;
   /** §C — auto-logout: clear creds in both stores, flip not-configured, notify. */
-  onPermanentFailure: (info: { code: number; message: string }) => Promise<void> | void;
+  onPermanentFailure: (info: { code: number; message: string }, revokedRefresh: RevokedRefreshMarker) => Promise<void> | void;
   /**
    * §A.1/§D — invoked AFTER a successful PROACTIVE-timer refresh has persisted +
    * swapped the in-memory token, so the runtime can perform the §D close-then-
@@ -138,12 +147,9 @@ export class RefreshManager {
   private inFlight: Promise<RefreshOutcome> | null = null;
   /** §A.3 — the access token a refresh was last attempted for. */
   private rejectedToken: string | null = null;
-  /**
-   * §B race — the refresh token we last successfully rotated AWAY from (now
-   * consumed server-side). A subsequent `code:10003` for this exact token is a
-   * consumed-rotation race, NOT a revocation, so it must not auto-logout.
-   */
+  /** Consumed-token history is diagnostic; a live successor is required to recover. */
   private lastRotatedFromToken: string | null = null;
+  private consecutiveRaceDowngrades = 0;
   /** §A.3 — epoch-ms of the last refresh attempt (any token). */
   private lastAttemptAt = 0;
   private proactiveTimer: TimerHandle | null = null;
@@ -217,11 +223,13 @@ export class RefreshManager {
         { refreshToken, deviceId: this.ports.deviceId },
       );
     } catch (err) {
+      this.consecutiveRaceDowngrades = 0;
       const message = err instanceof Error ? err.message : String(err);
       return { kind: "transient", message };
     }
 
     if (result.kind === "success") {
+      this.consecutiveRaceDowngrades = 0;
       // §0 rotation hazard — persist FIRST, swap SECOND. If persistence REJECTS
       // (a store/config write failed), DO NOT swap the in-memory token: a
       // sqlite-sourced agent must not keep a now-dead refresh token in its row
@@ -247,8 +255,7 @@ export class RefreshManager {
         accessToken: result.accessToken,
         refreshToken: result.refreshToken,
       });
-      // §B race — record the now-consumed refresh token so a later `10003` for it
-      // is recognized as a rotation race rather than a revocation.
+      // Keep rotation history for inspection; it never overrides the live-token check.
       this.lastRotatedFromToken = refreshToken;
       // Clear the latch; the access token has actually changed.
       this.rejectedToken = null;
@@ -257,25 +264,15 @@ export class RefreshManager {
     }
 
     if (result.kind === "permanent") {
-      // §B race — a `code:10003` is also returned for a refresh token already
-      // CONSUMED by a prior successful rotation (once the backend grace window
-      // no longer covers it). Before auto-logging-out
-      // (which wipes credentials and bricks the agent), distinguish that race
-      // from a genuine revocation. It is a race when EITHER the submitted token
-      // is one we already rotated away from, OR the live store refresh token has
-      // moved on since we read it (another worker rotated underneath us). In
-      // either case the credential chain is still alive — report transient (no
-      // latch, no logout) so the next attempt proceeds with the live token. A
-      // `code:400` (client bug) is never a race.
+      // A consumed-token race is recoverable only with a real live successor.
+      // Bound repeated downgrades, including across gateway re-enters.
       if (result.code === CODE_INVALID_REFRESH) {
         const liveRefresh = this.ports.getRefreshToken();
-        const rotatedByUs =
-          this.lastRotatedFromToken !== null && refreshToken === this.lastRotatedFromToken;
-        const rotatedUnderneath =
-          !!liveRefresh && liveRefresh.trim().length > 0 && liveRefresh !== refreshToken;
-        if (rotatedByUs || rotatedUnderneath) {
+        const hasSuccessor = !!liveRefresh?.trim() && liveRefresh !== refreshToken;
+        if (hasSuccessor && this.consecutiveRaceDowngrades < 2) {
+          this.consecutiveRaceDowngrades += 1;
           this.ports.log?.info?.(
-            `clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race (rotatedByUs=${rotatedByUs} rotatedUnderneath=${rotatedUnderneath}); recovering with live token`,
+            "clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race; recovering with live token",
           );
           return { kind: "transient", message: "refresh token already rotated (race); retrying with current token" };
         }
@@ -285,10 +282,14 @@ export class RefreshManager {
       this.ports.log?.error?.(
         `clawchat-plugin-openclaw refresh permanent failure code=${result.code}: ${result.message}`,
       );
-      await this.ports.onPermanentFailure({ code: result.code, message: result.message });
+      await this.ports.onPermanentFailure({
+        code: result.code,
+        message: result.message,
+      }, { fingerprint: fingerprintRefreshToken(refreshToken), revokedAt: this.now() });
       return { kind: "permanent", code: result.code, message: result.message };
     }
 
+    this.consecutiveRaceDowngrades = 0;
     // Transient — never auto-logout; the old refresh token is still valid.
     this.ports.log?.info?.(
       `clawchat-plugin-openclaw refresh transient failure: ${result.message}`,
@@ -470,11 +471,13 @@ export class RefreshManager {
     rejectedToken: string | null;
     lastAttemptAt: number;
     lastRotatedFromToken: string | null;
+    consecutiveRaceDowngrades: number;
   } {
     return {
       rejectedToken: this.rejectedToken,
       lastAttemptAt: this.lastAttemptAt,
       lastRotatedFromToken: this.lastRotatedFromToken,
+      consecutiveRaceDowngrades: this.consecutiveRaceDowngrades,
     };
   }
 
@@ -483,10 +486,12 @@ export class RefreshManager {
     rejectedToken: string | null;
     lastAttemptAt: number;
     lastRotatedFromToken?: string | null;
+    consecutiveRaceDowngrades?: number;
   }): void {
     this.rejectedToken = state.rejectedToken;
     this.lastAttemptAt = state.lastAttemptAt;
     this.lastRotatedFromToken = state.lastRotatedFromToken ?? null;
+    this.consecutiveRaceDowngrades = state.consecutiveRaceDowngrades ?? 0;
   }
 }
 

package/src/runtime.ts

@@ -36,7 +36,7 @@ import {
   type LivewareSampleSupervisorDeps,
 } from "./liveware-sample.ts";
 import { ClawlingApiError } from "./api-types.ts";
-import { RefreshManager } from "./refresh-manager.ts";
+import { RefreshManager, fingerprintRefreshToken, type RevokedRefreshMarker } from "./refresh-manager.ts";
 import { RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 import {
   runOpenclawClawlingLogin,
@@ -143,6 +143,9 @@ type RuntimeConnectionStore = Pick<
       | "upsertActivation"
       | "rotateActivationTokens"
       | "clearActivationCredentials"
+      | "getRevokedRefreshMarker"
+      | "setRevokedRefreshMarker"
+      | "clearRevokedRefreshMarker"
       | "insertMessage"
       | "claimMessageOnce"
       | "markMessageAcknowledged"
@@ -279,20 +282,27 @@ export function classifyHelloFailReason(
  * carries no `token` of its own (i.e. the access token itself came from
  * `CLAWCHAT_TOKEN`) — an env-provisioned pair can rotate, while a login-written
  * token is never paired with a stray refresh token left in the environment.
+ * A revoked marker also excludes a matching refresh fingerprint from either source.
  */
 function readConfigRefreshToken(
   cfg: OpenClawConfig,
   accountId: string,
+  revokedMarker?: RevokedRefreshMarker | null,
   env: NodeJS.ProcessEnv = process.env,
 ): string | null {
   const section = readOpenclawClawlingAccountSection(cfg, accountId);
   const refreshToken = section.refreshToken;
-  if (typeof refreshToken === "string" && refreshToken.trim()) return refreshToken.trim();
+  const usable = (token: unknown): string | null => {
+    const value = typeof token === "string" ? token.trim() : "";
+    return value && (!revokedMarker || fingerprintRefreshToken(value) !== revokedMarker.fingerprint)
+      ? value : null;
+  };
+  if (typeof refreshToken === "string" && refreshToken.trim()) return usable(refreshToken);
   if (normalizeOpenclawClawlingAccountId(accountId) !== DEFAULT_ACCOUNT_ID) return null;
   const configToken = section.token;
   if (typeof configToken === "string" && configToken.trim()) return null;
   const envRefreshToken = env[CLAWCHAT_REFRESH_TOKEN_ENV];
-  return typeof envRefreshToken === "string" && envRefreshToken.trim() ? envRefreshToken.trim() : null;
+  return usable(envRefreshToken);
 }
 
 function withFullVerboseDispatchConfig(cfg: OpenClawConfig, agentId: string): OpenClawConfig {
@@ -655,7 +665,9 @@ export interface StartGatewayParams {
    * min-interval floor) actually constrain a cross-reconnect refresh loop instead
    * of resetting on every fresh `RefreshManager`.
    */
-  refreshManagerState?: { rejectedToken: string | null; lastAttemptAt: number };
+  refreshManagerState?: Parameters<RefreshManager["restoreState"]>[0];
+  /** Internal guard when durable marker writes fail; never contains credentials. */
+  revokedRefreshMarker?: RevokedRefreshMarker;
   /**
    * Internal — the live (possibly rotated) refresh token, carried across a
    * §D/§B gateway re-enter. A rotation persists config with `afterWrite:{mode:
@@ -990,6 +1002,7 @@ function waitForActivationPoll(abortSignal: AbortSignal, ms: number): Promise<bo
 }
 
 async function waitForActivationCredentials(params: {
+  cfg: OpenClawConfig;
   account: ResolvedOpenclawClawlingAccount;
   abortSignal: AbortSignal;
   getStatus: () => ChannelAccountSnapshot;
@@ -998,16 +1011,23 @@ async function waitForActivationCredentials(params: {
   log?: Log;
   pollIntervalMs: number;
   rejectedActivationToken?: string;
+  revokedRefreshMarker?: RevokedRefreshMarker | null;
 }): Promise<{ account: ResolvedOpenclawClawlingAccount; source: "configured" | "sqlite" } | null> {
   const { abortSignal, getStatus, setStatus, store, log } = params;
   const accountId = params.account.accountId;
+  const revoked = params.revokedRefreshMarker;
+  const usable = (credentials: { accessToken: string; refreshToken: string | null }): boolean =>
+    credentials.accessToken !== params.rejectedActivationToken &&
+    (!revoked || (!!credentials.refreshToken &&
+      fingerprintRefreshToken(credentials.refreshToken) !== revoked.fingerprint));
   // SQLite-first: activation and token rotation persist to the activations
   // row, so a complete row is the durable credential source of truth even
   // when channel config/env also carries credentials. Config/env credentials
-  // only bootstrap the no-row case (the caller seeds a row from them).
+  // bootstrap the no-row case, or replace a revoked pair with a different
+  // refresh fingerprint (the caller seeds a row from the adopted pair).
   if (store?.getActivationCredentials) {
     const stored = store.getActivationCredentials({ platform: "openclaw", accountId });
-    if (stored && stored.accessToken !== params.rejectedActivationToken) {
+    if (stored && usable(stored)) {
       log?.info?.(
         `[${accountId}] clawchat-plugin-openclaw loaded activation credentials from sqlite`,
       );
@@ -1023,10 +1043,19 @@ async function waitForActivationCredentials(params: {
       };
     }
   }
-  if (accountHasConnectCredentials(params.account)) {
-    return { account: params.account, source: "configured" };
+  const configuredCredentials = (account: ResolvedOpenclawClawlingAccount) => {
+    const refreshToken = readConfigRefreshToken(params.cfg, accountId, revoked);
+    return accountHasConnectCredentials(account) && usable({ accessToken: account.token, refreshToken })
+      ? { account, source: "configured" as const } : null;
+  };
+  const configured = configuredCredentials(params.account);
+  if (configured) return configured;
+  if (revoked) {
+    log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${CLAWCHAT_TOKEN_EXPIRED_MESSAGE}`);
+    setStatus({ ...getStatus(), connected: false, configured: false, running: false,
+      lastError: CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR });
   }
-  if (!store?.getActivationCredentials) {
+  if (!revoked && !store?.getActivationCredentials) {
     const message = "Clawling Chat token is missing and activation database is unavailable";
     log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${message}`);
     setStatus({
@@ -1042,7 +1071,7 @@ async function waitForActivationCredentials(params: {
   log?.info?.(
     `[${accountId}] clawchat-plugin-openclaw waiting for activation credentials in sqlite`,
   );
-  setStatus({
+  if (!revoked) setStatus({
     ...getStatus(),
     connected: false,
     configured: true,
@@ -1051,22 +1080,9 @@ async function waitForActivationCredentials(params: {
   });
 
   while (!abortSignal.aborted) {
-    const credentials = store.getActivationCredentials({
-      platform: "openclaw",
-      accountId,
-    });
-    if (credentials) {
-      if (credentials.accessToken === params.rejectedActivationToken) {
-        log?.debug?.(
-          `[${accountId}] clawchat-plugin-openclaw activation credential poll heartbeat status=rejected_token_unchanged intervalMs=${params.pollIntervalMs}`,
-        );
-        const shouldContinue = await waitForActivationPoll(abortSignal, params.pollIntervalMs);
-        if (!shouldContinue) break;
-        continue;
-      }
-      log?.info?.(
-        `[${accountId}] clawchat-plugin-openclaw loaded activation credentials from sqlite`,
-      );
+    const credentials = store?.getActivationCredentials?.({ platform: "openclaw", accountId });
+    if (credentials && usable(credentials)) {
+      log?.info?.(`[${accountId}] clawchat-plugin-openclaw loaded activation credentials from sqlite`);
       return {
         source: "sqlite",
         account: {
@@ -1078,8 +1094,14 @@ async function waitForActivationCredentials(params: {
         },
       };
     }
+    if (revoked) {
+      // Re-read env credentials while parked so a new pair can recover without
+      // another gateway invocation. Config credentials use the supplied snapshot.
+      const replacement = configuredCredentials(resolveOpenclawClawlingAccount(params.cfg, accountId));
+      if (replacement) return replacement;
+    }
     log?.debug?.(
-      `[${accountId}] clawchat-plugin-openclaw activation credential poll heartbeat status=waiting intervalMs=${params.pollIntervalMs}`,
+      `[${accountId}] clawchat-plugin-openclaw activation credential poll heartbeat status=${credentials ? "rejected_token_unchanged" : "waiting"} intervalMs=${params.pollIntervalMs}`,
     );
     const shouldContinue = await waitForActivationPoll(abortSignal, params.pollIntervalMs);
     if (!shouldContinue) break;
@@ -1097,7 +1119,25 @@ async function waitForActivationCredentials(params: {
 let warnedBelowHostFloor = false;
 let loggedHostToolSearch = false;
 
+/** Re-pair lifecycle owned by one gateway invocation (see performAutoLogout). */
+type GatewayLifecycle = { rePairWait?: Promise<void> };
+
 export async function startOpenclawClawlingGateway(params: StartGatewayParams): Promise<void> {
+  // Every exit, including an interrupted connect or abort during logout, must
+  // wait for the one re-pair lifecycle this invocation started: settling the
+  // host's startAccount task early would make the host restart the channel.
+  const lifecycle: GatewayLifecycle = {};
+  try {
+    await runOpenclawClawlingGateway(params, lifecycle);
+  } finally {
+    await lifecycle.rePairWait;
+  }
+}
+
+async function runOpenclawClawlingGateway(
+  params: StartGatewayParams,
+  lifecycle: GatewayLifecycle,
+): Promise<void> {
   const { cfg, abortSignal, setStatus, getStatus, log } = params;
   let account = params.account;
   // Obtain PluginRuntime from the stored runtime set via setOpenclawClawlingRuntime.
@@ -1162,7 +1202,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       log,
     });
   }
+  const revokedRefreshMarker = params.revokedRefreshMarker ??
+    store?.getRevokedRefreshMarker?.({ platform: "openclaw", accountId });
   const activationAccount = await waitForActivationCredentials({
+    cfg,
     account,
     abortSignal,
     getStatus,
@@ -1171,9 +1214,15 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     log,
     pollIntervalMs: params.activationPollIntervalMs ?? ACTIVATION_CREDENTIAL_POLL_INTERVAL_MS,
     rejectedActivationToken: params.rejectedActivationToken,
+    revokedRefreshMarker,
   });
   if (!activationAccount) return;
   account = activationAccount.account;
+  // Reset in-memory refresh guards only after adopting a different pair.
+  if (revokedRefreshMarker) {
+    params = { ...params, revokedRefreshMarker: undefined, refreshTokenOverride: undefined,
+      refreshManagerState: undefined, rejectedActivationToken: undefined };
+  }
   // Config/env bootstrap seeding: converge on SQLite as the single durable
   // credential store, so token rotation always has a row to update and the
   // next startup resolves SQLite-first to the same credentials.
@@ -1185,7 +1234,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         userId: account.userId,
         ownerUserId: account.ownerUserId,
         accessToken: account.token,
-        refreshToken: readConfigRefreshToken(cfg, accountId),
+        refreshToken: readConfigRefreshToken(cfg, accountId, revokedRefreshMarker),
         loginMethod: "config-seed",
         deviceId: CHANNEL_ID,
       });
@@ -1195,6 +1244,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       );
     }
   }
+  if (revokedRefreshMarker && store) {
+    if (store.clearRevokedRefreshMarker?.({ platform: "openclaw", accountId }) !== true) {
+      log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear sqlite revoked marker after activation`);
+    }
+  }
   // Paired: link the report row via the authenticated endpoint, reusing the
   // SAME frozen device_id so the backend upserts the existing unpaired row.
   void reportPluginVersionSafe({
@@ -1391,13 +1445,13 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // blanks them (auto-logout); otherwise persists the rotated pair.
   const persistConfigTokens = async (
     tokens: { accessToken: string; refreshToken: string } | null,
-  ): Promise<void> => {
+  ): Promise<boolean> => {
     const mutateConfigFile = resolveMutateConfigFile();
     if (!mutateConfigFile) {
       log?.error?.(
         `[${accountId}] clawchat-plugin-openclaw config persistence unavailable; cannot ${tokens ? "rotate" : "clear"} tokens in config`,
       );
-      return;
+      return false;
     }
     await mutateConfigFile({
       afterWrite: { mode: "none", reason: "clawchat-plugin-openclaw token refresh" },
@@ -1411,6 +1465,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         );
       },
     });
+    return true;
   };
 
   let lastHelloFailTraceId = "-";
@@ -1432,6 +1487,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   let reconnectWithRefreshedToken = false;
   // §C — set once auto-logout has fired so we don't double-emit or reconnect.
   let autoLoggedOut = false;
+  let refreshClient: ClawlingChatClient | undefined;
+  let autoLogoutCleanup: Promise<void> | undefined;
 
   // §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
@@ -1444,37 +1501,62 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // §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;
+  const performAutoLogout = (
+    info: { code: number; message: string }, marker: RevokedRefreshMarker,
+  ): Promise<void> => {
+    if (autoLogoutCleanup) return autoLogoutCleanup;
     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();
+    refreshManager.stop();
+    activeClients.delete(accountId);
+    try { refreshClient?.close(); } catch { /* Best effort shutdown. */ }
+    // Write the marker independently BEFORE clearing, so a failed clear cannot
+    // resurrect this rejected credential at the next process start.
+    autoLogoutCleanup = (async () => {
+      const markerInput = { platform: "openclaw", accountId, ...marker };
+      try {
+        if (store?.setRevokedRefreshMarker?.(markerInput) !== true) {
+          log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to persist sqlite revoked refresh marker`);
+        }
+      } catch {
+        log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to persist sqlite revoked refresh marker`);
+      }
+      try {
+        if (store?.clearActivationCredentials?.({ platform: "openclaw", accountId }) !== true) {
+          log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear sqlite credentials on auto-logout`);
+        }
+      } catch {
+        log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear sqlite credentials on auto-logout`);
+      }
+      try {
+        if (!await persistConfigTokens(null)) throw new Error("config mutation unavailable");
+      } catch {
+        log?.warn?.(`[${accountId}] clawchat-plugin-openclaw failed to clear config credentials on auto-logout`);
+      }
+      // 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();
+    })();
+    // Assign the lifetime before yielding, including when config clearing is
+    // still pending and closing the old socket interrupts client.connect().
+    lifecycle.rePairWait = autoLogoutCleanup.then(() => startOpenclawClawlingGateway({
+      ...params, boundaryWarningIssued: true,
+      account: { ...account, configured: false, token: "" },
+      revokedRefreshMarker: marker, refreshTokenOverride: undefined,
+      refreshManagerState: undefined, rejectedActivationToken: undefined,
+      refreshReconnectDepth: undefined, refreshReconnectWindowStartedAt: undefined,
+    }));
+    return autoLogoutCleanup;
   };
 
   // §C.1.4 — surface the permanent-expiry message to the user/operator. The
@@ -1509,7 +1591,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     (activationAccount.source === "sqlite" && store?.getActivationCredentials
       ? store.getActivationCredentials({ platform: "openclaw", accountId })?.refreshToken
       : null) ??
-    readConfigRefreshToken(cfg, accountId);
+    readConfigRefreshToken(cfg, accountId, revokedRefreshMarker);
 
   const refreshManager = new RefreshManager({
     baseUrl: account.baseUrl,
@@ -1569,7 +1651,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       // No SQLite store available — channel config is the only durable
       // store, so its write failure must reject and keep the refresh
       // transient (pre-existing behavior for store-less test transports).
-      await persistConfigTokens(tokens);
+      if (!await persistConfigTokens(tokens)) {
+        throw new Error("clawchat-plugin-openclaw config persistence unavailable");
+      }
     },
     swapInMemoryTokens: (tokens) => {
       account = { ...account, token: tokens.accessToken, configured: true };
@@ -1848,7 +1932,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     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.
+      // Wait for re-pair or abort rather than settling the host channel task.
+      await lifecycle.rePairWait;
       return;
     }
     // success swaps the in-memory token in place; transient/skipped just connect
@@ -1896,6 +1981,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       },
     },
   });
+  refreshClient = client;
   log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client created`);
 
   // §A.3/§A.4 — recompute the refresh-driven reconnect streak (depth + window).
@@ -2036,7 +2122,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     }
     const outcome = await refreshManager.refresh(reason);
     if (abortSignal.aborted) return "fallthrough";
-    if (autoLoggedOut) return "handled"; // permanent → manager auto-logged-out.
+    if (autoLoggedOut) {
+      await lifecycle.rePairWait;
+      return "handled";
+    }
     if (outcome.kind === "success") {
       await closeAndReconnectWithRefreshedToken(reason);
       return "handled";
@@ -3803,8 +3892,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       // return on abort, but only AFTER it has already taken the idempotency claim
       // (`claimInboundTurn` runs BEFORE the gate wait there, so the frame is durably
       // persisted before the interruptible wait — required by legacy advance-on-
-      // write delivery, where a frame written before a disconnect is not re-delivered
-      // on reconnect; see docs/client-integration.md §11.7). So even an ingest-time
+      // write delivery, where a frame written before a disconnect is not reliably
+      // re-delivered on reconnect (legacy may lose OR replay; a replay is deduped by
+      // the claim); see docs/client-integration.md §11.7). So even an ingest-time
       // abort keeps the frame; it just skips dispatch. Here at FLUSH the batch was
       // likewise already claimed at ingest AND `flush()` has already removed it from
       // the coalescer's pending set. An abort early-return would therefore silently
@@ -3940,11 +4030,14 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       // can interrupt. This client does NOT advertise `reliable_delivery`
       // (src/ws-client.ts), so under legacy delivery the server's replay cursor
       // advances on socket-WRITE (docs/client-integration.md §11.7): a frame
-      // already written before a disconnect is NOT re-delivered on reconnect.
+      // already written before a disconnect is NOT reliably re-delivered on
+      // reconnect. Legacy is not at-most-once either — a multi-replica server
+      // (relayed frames do not advance the cursor) or a failed cursor write can
+      // replay frames already received — and the claim below dedupes those.
       // `claimMessageOnce` is the ONLY durability an inbound has, and the store
       // never reprocesses undispatched inbounds. So if we claimed only AFTER the
-      // wait, a shutdown-mid-wait would leave the frame neither persisted NOR
-      // replayed — permanently lost. Claiming first makes it durable; the abort
+      // wait, a shutdown-mid-wait would leave the frame unpersisted with no
+      // guaranteed replay — lost. Claiming first makes it durable; the abort
       // check below then returns without dispatching, but the frame is kept.
       // `claimInboundTurn` is INSERT OR IGNORE, so a genuine duplicate (same
       // message_id) is still deduped here exactly once. The claim fails CLOSED:
@@ -4281,6 +4374,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     await client.connect();
     log?.info?.(`[${accountId}] clawchat-plugin-openclaw runtime client.connect() resolved`);
   } catch (err) {
+    if (autoLoggedOut) {
+      await lifecycle.rePairWait;
+      return;
+    }
     const classified = classifyClawlingClientError(err);
     if (classified.kind === "auth") {
       // §A.2/§B — initial-connect hello-fail(auth). Do NOT pre-flip
@@ -4356,6 +4453,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     );
     return;
   }
+  if (autoLoggedOut) {
+    await lifecycle.rePairWait;
+    return;
+  }
   activeClients.set(accountId, client);
   // Text "@name" autolinking on outbound group sends reads the same cached
   // roster (participant ids + nicknames) the group prompt shows the model.

package/src/storage.ts

@@ -1,3 +1,4 @@
+import type { RevokedRefreshMarker } from "./refresh-manager.ts";
 import fs from "node:fs";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
@@ -427,6 +428,19 @@ CREATE INDEX IF NOT EXISTS idx_clawchat_messages_protocol_message_id_nocase
     sql: `
 CREATE INDEX IF NOT EXISTS idx_clawchat_messages_chat_id_nocase
   ON clawchat_messages(chat_id COLLATE NOCASE);
+`,
+  },
+  {
+    version: 13,
+    name: "revoked_refresh_tokens",
+    sql: `
+CREATE TABLE IF NOT EXISTS revoked_refresh_tokens (
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  revoked_at INTEGER NOT NULL,
+  PRIMARY KEY (platform, account_id)
+);
 `,
   },
 ];
@@ -600,6 +614,34 @@ export class ClawChatStore {
     });
   }
 
+  setRevokedRefreshMarker(input: ClearActivationCredentialsInput & RevokedRefreshMarker): boolean | null {
+    return this.write(() => {
+      this.requireDb().prepare(`INSERT INTO revoked_refresh_tokens
+        (platform, account_id, fingerprint, revoked_at) VALUES (?, ?, ?, ?)
+        ON CONFLICT(platform, account_id) DO UPDATE SET
+        fingerprint = excluded.fingerprint, revoked_at = excluded.revoked_at`)
+        .run(input.platform, input.accountId, input.fingerprint, input.revokedAt);
+      return true;
+    });
+  }
+
+  getRevokedRefreshMarker(input: ClearActivationCredentialsInput): RevokedRefreshMarker | null {
+    return this.read(() => {
+      const row = this.requireDb().prepare(`SELECT fingerprint, revoked_at AS revokedAt
+        FROM revoked_refresh_tokens WHERE platform = ? AND account_id = ?`)
+        .get(input.platform, input.accountId) as RevokedRefreshMarker | undefined;
+      return row ?? null;
+    }) ?? null;
+  }
+
+  clearRevokedRefreshMarker(input: ClearActivationCredentialsInput): boolean | null {
+    return this.write(() => {
+      this.requireDb().prepare(`DELETE FROM revoked_refresh_tokens WHERE platform = ? AND account_id = ?`)
+        .run(input.platform, input.accountId);
+      return true;
+    });
+  }
+
   getActivationCredentials(input: ConversationAccountInput): ActivationCredentials | null {
     return this.read(() => {
       const row = this.requireDb()