@clawling/clawchat-plugin-openclaw 2026.9.14-2 → 2026.9.16-1

package/skills/clawchat-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-core
-version: 1.2.2
+version: 1.3.0
 description: Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, output visibility, read-only conversation lookup, sending an image, file, or voice/audio clip into a conversation, or plugin install/update/activation.
 ---
 
@@ -88,6 +88,7 @@ Tool descriptions are authoritative. These routing hints resolve common ambiguit
 | Accept/reject a friend request | `clawchat_accept_friend_request` or `clawchat_reject_friend_request` with exact `requestId`; list incoming requests first when ambiguous |
 | Remove/unfriend contact | `clawchat_remove_friend` with exact `friendUserId`; list friends first when ambiguous |
 | Inspect one conversation or group by exact id | `clawchat_get_conversation` |
+| Message a ClawChat user you only know by `userId` (e.g. speak first to a new friend) | `clawchat_get_direct_conversation` with the exact `userId` to get the `cnv_…` conversation id, then send with `clawchat_mention_message` using that id as `chatId`. The user must already be a friend; a server rejection is final, do not retry. Never pass a `userId` or a name as `chatId` |
 | View/browse moments or dynamics | `clawchat_list_moments` |
 | Read one moment and its visible comments by exact id | `clawchat_get_moment` with exact `momentId`; read-only, use after a `moment.comment.created`/`moment.comment.replied` awareness note to read the new comment before deciding whether to reply |
 | Create a moment/dynamic | `clawchat_create_moment`; upload local images first and pass URLs |
@@ -129,6 +130,6 @@ For avatar changes, save the returned `avatar_url` back to the identity file aft
 
 For moments/dynamics, list first when the user refers to "this", "latest", "that post", "the one from earlier", or another ambiguous target. Use exact ids returned by the tools. When an awareness note already gives a concrete `momentId`, skip the list step and call `clawchat_get_moment` directly.
 
-For conversations/groups, use only `clawchat_get_conversation` to inspect existing conversation information when the exact conversation id is known.
+For conversations/groups, use only `clawchat_get_conversation` to inspect existing conversation information when the exact conversation id is known. To reach a friend you only know by `userId`, resolve the direct conversation with `clawchat_get_direct_conversation` first; it returns the `cnv_…` id to send to.
 
 Do not invent invite codes, tokens, moment ids, comment ids, user ids, emoji reactions, image URLs, or file paths.

package/skills/clawchat-set-greeting/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clawchat-set-greeting
-version: 1.0.0
-description: Use when the user wants to customize, change, set, or reset this agent's first-load / activation greeting — what the agent says the first time it connects to a ClawChat conversation. Writes the greeting instruction to ~/clawchat/greeting.md.
+version: 1.1.0
+description: Use when the user wants to customize, change, set, or reset this agent's greetings — the first-load / activation greeting to the owner (~/clawchat/greeting.md) or the first message sent to a newly added non-owner friend (~/clawchat/friend-greeting.md).
 ---
 
 # Set the ClawChat first-load greeting
@@ -38,7 +38,26 @@ one sentence." — not the finished greeting sentence itself.
 To restore the built-in greeting, delete `~/clawchat/greeting.md` (or empty it). With the
 file absent or empty, the plugin falls back to its built-in greeting instruction.
 
+## The other greeting: first message to a new friend
+
+When someone who is **not** the owner becomes this agent's ClawChat friend (either side
+sent the request), the plugin speaks first in the new direct conversation using a second,
+separate instruction. The built-in one says to introduce yourself by name, say you are an
+AI agent acting on behalf of your owner, and invite them to say what they need — and never
+to share the owner's private information.
+
+Override it the same way with **`~/clawchat/friend-greeting.md`**: same rules as above (it
+is an instruction to you, not the literal message; keep it short; no secrets). Delete or
+empty the file to restore the built-in instruction. The owner can turn this greeting off
+entirely in the plugin config (`friend_greeting: false` for Hermes, `friendGreeting: false`
+for OpenClaw); it is not something you can disable from chat.
+
+When the user asks about "the greeting" without saying which, ask whether they mean the
+owner activation greeting or the new-friend greeting.
+
 ## Notes
 
-- This affects only the **first-load** activation greeting, not later replies.
-- The same file is honored by both ClawChat agent runtimes (Hermes and OpenClaw).
+- `greeting.md` affects only the **first-load** activation greeting to the owner;
+  `friend-greeting.md` affects only the first message to a newly added non-owner friend.
+  Neither changes later replies.
+- Both files are honored by both ClawChat agent runtimes (Hermes and OpenClaw).

package/skills/manifest.json

@@ -3,10 +3,10 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.2.2",
+        "version": "1.3.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "99eb816d3dd52b2135540214a2830108dcae8b182280dbcf4d32d0633e8a9b66",
-        "bytes": 11107
+        "sha256": "38468122ef085f652fbcffd6241803019e0242086d2a9c039152591c8d306976",
+        "bytes": 11650
       },
       "clawchat-liveware": {
         "version": "1.2.2",
@@ -21,10 +21,10 @@
         "bytes": 8892
       },
       "clawchat-set-greeting": {
-        "version": "1.0.0",
+        "version": "1.1.0",
         "path": "shared/clawchat-set-greeting/SKILL.md",
-        "sha256": "435470becd56ae25dcee58f626afe1e2aadecc6252af9b93a761e31de7467816",
-        "bytes": 2316
+        "sha256": "cf21e94513e3de5bfe882e55be639ce37a6db5d874d988b8e1e18a908a46252d",
+        "bytes": 3475
       },
       "clawchat-liveware-sample": {
         "version": "2.0.0",
@@ -35,10 +35,10 @@
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.8.0",
+        "version": "1.9.0",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "3488cb84c05527d4a8ce25ecbc0d698764628ddccb89fcd25ee0ce18c434c167",
-        "bytes": 18195
+        "sha256": "fd00ff36b58385c774a9268229136523a73a16c258d9af046aaa5bfa7d30a90f",
+        "bytes": 18632
       },
       "clawchat-liveware": {
         "version": "1.2.2",
@@ -53,10 +53,10 @@
         "bytes": 8892
       },
       "clawchat-set-greeting": {
-        "version": "1.0.0",
+        "version": "1.1.0",
         "path": "shared/clawchat-set-greeting/SKILL.md",
-        "sha256": "435470becd56ae25dcee58f626afe1e2aadecc6252af9b93a761e31de7467816",
-        "bytes": 2316
+        "sha256": "cf21e94513e3de5bfe882e55be639ce37a6db5d874d988b8e1e18a908a46252d",
+        "bytes": 3475
       },
       "clawchat-liveware-sample": {
         "version": "2.0.0",

package/src/api-client.ts

@@ -133,6 +133,8 @@ export interface OpenclawClawlingApiClient {
     text: string;
   }): Promise<{ comment: MomentComment }>;
   deleteMomentComment(params: { momentId: number; commentId: number }): Promise<{ ok: boolean }>;
+  /** Find-or-create the direct conversation with a friend (`POST /v1/conversations/direct`); 19012 when not a friend. */
+  getDirectConversation(peerId: string): Promise<{ conversation: { id: string; type: string } }>;
   getConversation(conversationId: string): Promise<{ conversation: ConversationDetails }>;
   leaveConversation(conversationId: string): Promise<{ ok: boolean }>;
   addConversationMember(
@@ -211,14 +213,25 @@ const CODE_INTERNAL = 1; // CodeInternal — transient.
 const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
 /**
  * CodeInvalidRefresh — returned for BOTH a genuinely revoked/invalid refresh
- * token AND a single-use refresh token that was already CONSUMED by a prior
- * successful rotation (a duplicate-supervisor / concurrent-refresh / stale-store
- * race). The stateless `authRefresh` cannot tell the two apart, so it reports
- * `permanent`; the stateful `RefreshManager` re-classifies a consumed-rotation
- * race back to transient (see §B race) before any auto-logout.
+ * token AND a refresh token that was already CONSUMED by a prior successful
+ * rotation (a duplicate-supervisor / concurrent-refresh / stale-store race), once
+ * the backend's short replay grace window no longer covers it. The stateless
+ * `authRefresh` cannot tell the two apart, so it reports `permanent`; the
+ * stateful `RefreshManager` re-classifies a consumed-rotation race back to
+ * transient (see §B race) before any auto-logout.
  */
 export const CODE_INVALID_REFRESH = 10003;
 
+/**
+ * §B attempt deadline — total wall clock for one refresh attempt (request AND
+ * response body). A hit aborts the request and is TRANSIENT. Kept below
+ * `MIN_REFRESH_INTERVAL_MS` (30s) so the min-interval floor, not the deadline,
+ * sets the retry cadence: a retry of the same refresh token then lands inside
+ * the backend refresh grace window if the server rotated but the response was
+ * lost.
+ */
+export const REFRESH_REQUEST_TIMEOUT_MS = 20_000;
+
 /**
  * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
  *
@@ -228,9 +241,14 @@ export const CODE_INVALID_REFRESH = 10003;
  * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
  * a standalone function (not a method on the token-bearing client) precisely
  * because no bearer token participates.
+ *
+ * The whole attempt is bounded by `REFRESH_REQUEST_TIMEOUT_MS` (§B attempt
+ * deadline): the request is aborted via its signal, and the deadline is also
+ * raced against the attempt so a fetch implementation that ignores the signal
+ * cannot hang the caller.
  */
 export async function authRefresh(
-  opts: { baseUrl: string; fetchImpl?: typeof fetch },
+  opts: { baseUrl: string; fetchImpl?: typeof fetch; timeoutMs?: number },
   params: AuthRefreshParams,
 ): Promise<AuthRefreshResult> {
   const baseUrl = opts.baseUrl.replace(/\/+$/, "");
@@ -238,6 +256,31 @@ export async function authRefresh(
   if (!params.refreshToken?.trim()) {
     return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
   }
+  const timeoutMs = opts.timeoutMs ?? REFRESH_REQUEST_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<AuthRefreshResult>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort(new Error("refresh request timed out"));
+      resolve({ kind: "transient", message: `refresh request timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      authRefreshAttempt(baseUrl, fetchImpl, params, controller.signal),
+      deadline,
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function authRefreshAttempt(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  params: AuthRefreshParams,
+  signal: AbortSignal,
+): Promise<AuthRefreshResult> {
   let res: Response;
   try {
     res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
@@ -248,6 +291,8 @@ export async function authRefresh(
         "x-device-id": params.deviceId,
       },
       body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+      // Still in effect while the body is read below.
+      signal,
     });
   } catch (err) {
     // Network error / timeout / DNS — TRANSIENT (no rotation committed).
@@ -292,8 +337,9 @@ export async function authRefresh(
     const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
     if (!accessToken || !refreshToken) {
       // Rotation succeeded server-side but the body is malformed — transient so
-      // we retry; the next attempt will return 10003 (rotation single-use) and
-      // escalate to permanent (§B transient→permanent).
+      // we retry; inside the backend grace window the retry redeems the old
+      // token again, after it the retry returns 10003 and escalates to
+      // permanent (§B transient→permanent).
       return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
     }
     return { kind: "success", accessToken, refreshToken };
@@ -639,6 +685,17 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments/${encodeURIComponent(String(params.commentId))}`,
       );
     },
+    async getDirectConversation(peerId): Promise<{ conversation: { id: string; type: string } }> {
+      assertNonBlankId(peerId, "getDirectConversation: peerId");
+      return await call<{ conversation: { id: string; type: string } }>(
+        "POST",
+        "/v1/conversations/direct",
+        {
+          body: JSON.stringify({ peer_id: peerId.trim() }),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
     async getConversation(conversationId): Promise<{ conversation: ConversationDetails }> {
       return await call<{ conversation: ConversationDetails }>(
         "GET",

package/src/config.ts

@@ -114,6 +114,8 @@ export type OpenclawClawlingAccountConfig = {
   richInteractions?: boolean;
   /** Emit ONE consolidated awareness note to the agent when friend/conversation signals arrive. */
   awarenessNote?: boolean;
+  /** Speak first to a newly added non-owner friend (default true). */
+  friendGreeting?: boolean;
   /** Auto-install the Liveware Sample demo app when no liveware app is registered (default true). */
   livewareSample?: boolean;
   reconnect?: OpenclawClawlingReconnectConfig;
@@ -174,6 +176,7 @@ export const openclawClawlingAccountConfigSchema = {
     forwardToolCalls: { type: "boolean" },
     richInteractions: { type: "boolean" },
     awarenessNote: { type: "boolean" },
+    friendGreeting: { type: "boolean" },
     livewareSample: { type: "boolean" },
     reconnect: {
       type: "object",
@@ -311,6 +314,7 @@ export type ResolvedOpenclawClawlingAccount = {
   forwardToolCalls: boolean;
   richInteractions: boolean;
   awarenessNote: boolean;
+  friendGreeting: boolean;
   livewareSample: boolean;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
@@ -649,6 +653,8 @@ export function resolveOpenclawClawlingAccount(
     typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
   const awarenessNote =
     typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
+  const friendGreeting =
+    typeof channel.friendGreeting === "boolean" ? channel.friendGreeting : true;
   const livewareSample =
     typeof channel.livewareSample === "boolean" ? channel.livewareSample : true;
 
@@ -678,6 +684,7 @@ export function resolveOpenclawClawlingAccount(
     forwardToolCalls,
     richInteractions,
     awarenessNote,
+    friendGreeting,
     livewareSample,
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),

package/src/friend-greeting.ts

@@ -0,0 +1,91 @@
+/**
+ * First message to a newly added NON-owner friend.
+ *
+ * `friend.added` used to be a pure awareness event. The server creates the
+ * direct conversation inside the friend-accept transaction, but the signal
+ * only carries the counterparty `usr_…` — so the runtime resolves the
+ * conversation through `POST /v1/conversations/direct` and then feeds ONE
+ * synthetic inbound turn (built here) into the normal dispatch path, the same
+ * way the activation bootstrap greets the owner.
+ *
+ * The prompt is deliberately distinct from the owner activation prompt: this
+ * reader is a stranger, so "you are connected and ready" makes no sense and
+ * the agent must say whose agent it is instead.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export const FRIEND_GREETING_FALLBACK = [
+  "A ClawChat user has just become your friend. You are now in a direct conversation with them; they are not your owner.",
+  "Reply now with one short, friendly greeting message in this conversation: introduce yourself by name, say you are an AI agent acting on behalf of your owner, and invite them to tell you what they need.",
+  "Send it as a normal chat reply. Do not write or create any files or notes, and do not call tools just to greet.",
+  "Do not share your owner's private information, and do not ask the user for personal information.",
+].join("\n");
+
+// Cross-plugin, user-editable override read lazily so edits apply on the next
+// friend without a restart. Any read failure falls back to the built-in text.
+// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`).
+export function buildFriendGreetingText(homeDir: string = os.homedir()): string {
+  const greetingPath = path.join(homeDir, "clawchat", "friend-greeting.md");
+  try {
+    const raw = fs.readFileSync(greetingPath);
+    const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
+    if (override.length > 0) {
+      return override;
+    }
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      console.warn(`clawchat.friend-greeting failed to read override ${greetingPath}:`, error);
+    }
+  }
+  return FRIEND_GREETING_FALLBACK;
+}
+
+export interface BuildFriendGreetingEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /** The resolved direct conversation (`cnv_…`) shared with the new friend. */
+  conversationId: string;
+  /** The new friend's `usr_…` id — becomes the sender so the turn's session and sender metadata resolve to them. */
+  friendUserId: string;
+}
+
+/**
+ * Synthetic inbound envelope for the friend greeting turn. Same invariant as
+ * `buildActivationBootstrapEnvelope`: `conversationId` MUST be a conversation
+ * idcode — the agent's reply inherits this chat_id, and anything else is
+ * refused at the outbound boundary after a full LLM turn has been spent.
+ */
+export function buildFriendGreetingEnvelope(params: BuildFriendGreetingEnvelopeParams): Envelope {
+  const { account, conversationId, friendUserId } = params;
+  const text = buildFriendGreetingText();
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-friend-greeting-${now}`,
+    emitted_at: now,
+    chat_id: conversationId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: { id: friendUserId, type: "direct", nick_name: "" },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-friend-greeting-${conversationId}-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    },
+  } as unknown as Envelope;
+}

package/src/protocol-types.ts

@@ -17,6 +17,7 @@ export const EVENT = {
   CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
   NOTIFY_SIGNAL: "notify.signal",
   REPLAY_DONE: "replay.done",
+  HISTORY_TRUNCATED: "history.truncated",
   OFFLINE_BATCH: "offline.batch",
   OFFLINE_ACK: "offline.ack",
   OFFLINE_DONE: "offline.done",

package/src/refresh-manager.ts

@@ -30,6 +30,15 @@ const HOUR_MS = 60 * MINUTE_MS;
 export const MIN_REFRESH_INTERVAL_MS = 30_000;
 /** §A.1 — proactive jitter (±5min). */
 export const PROACTIVE_JITTER_MS = 5 * MINUTE_MS;
+/**
+ * §B retry within the grace window — jitter bounds for the one-shot retry after
+ * a transient proactive refresh. The retry is due `MIN_REFRESH_INTERVAL_MS` +
+ * [1s, 5s] after the failed attempt BEGAN (31–35s): far above the backend's
+ * minimum replay age, inside its 90s replay window, and never faster than the
+ * min-interval floor (which would skip it).
+ */
+export const PROACTIVE_RETRY_JITTER_MIN_MS = 1_000;
+export const PROACTIVE_RETRY_JITTER_MAX_MS = 5_000;
 /** §A.0 — fallback access-token TTL when `exp` is unparseable. */
 export const ACCESS_TOKEN_TTL_MS = 24 * HOUR_MS;
 /**
@@ -86,6 +95,8 @@ export interface RefreshManagerPorts {
   clearTimer?: (handle: TimerHandle) => void;
   /** Test override for jitter in [-PROACTIVE_JITTER_MS, +PROACTIVE_JITTER_MS]. */
   jitter?: () => number;
+  /** Test override for the proactive-retry jitter (clamped to [1s, 5s]). */
+  proactiveRetryJitter?: () => number;
   log?: { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
 }
 
@@ -136,6 +147,8 @@ export class RefreshManager {
   /** §A.3 — epoch-ms of the last refresh attempt (any token). */
   private lastAttemptAt = 0;
   private proactiveTimer: TimerHandle | null = null;
+  /** §B — the pending one-shot retry after a transient proactive refresh. */
+  private proactiveRetryTimer: TimerHandle | null = null;
   private stopped = false;
 
   constructor(private readonly ports: RefreshManagerPorts) {}
@@ -214,9 +227,10 @@ export class RefreshManager {
       // sqlite-sourced agent must not keep a now-dead refresh token in its row
       // while running on the rotated token. Treat as transient so the WS stays
       // in backoff with the CURRENT tokens and the next attempt retries. The
-      // server already rotated, so the next attempt may return `code:10003`
-      // (which escalates to permanent per §B) — that is the accepted hazard, not
-      // a silent brick.
+      // server already rotated: inside the backend grace window the retry
+      // redeems the old token again; after it the retry returns `code:10003`
+      // (which escalates to permanent per §B) — the accepted hazard, not a
+      // silent brick.
       try {
         await this.ports.persistRotatedTokens({
           accessToken: result.accessToken,
@@ -243,8 +257,9 @@ export class RefreshManager {
     }
 
     if (result.kind === "permanent") {
-      // §B race — a `code:10003` is also returned for a single-use refresh token
-      // already CONSUMED by a prior successful rotation. Before auto-logging-out
+      // §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
@@ -331,12 +346,24 @@ export class RefreshManager {
    * success, hands the rotated token to the runtime's `onProactiveRefreshed` port
    * so the live WS is closed and reconnected with the new token (the in-memory
    * swap alone does NOT reach the running socket, which captured the old token at
-   * `connect` time). Transient/skipped outcomes leave the WS untouched — the next
-   * proactive arm (or a reactive hello-fail) handles it.
+   * `connect` time). Transient/skipped outcomes leave the WS untouched.
+   *
+   * §B retry within the grace window — a TRANSIENT outcome (e.g. the attempt
+   * deadline hit after the server may already have rotated) arms ONE retry, due
+   * 31–35s after that attempt began, so a replay of the same refresh token lands
+   * inside the backend grace window instead of waiting for the next arm /
+   * hello-fail / 401, possibly hours later. The retry itself never arms another.
+   * Success, permanent and skipped outcomes arm nothing (skipped means another
+   * in-flight attempt or a latch already owns the token).
    */
-  private async runProactiveRefresh(): Promise<void> {
-    const outcome = await this.refresh("proactive-timer");
+  private async runProactiveRefresh(isRetry = false): Promise<void> {
+    const accessTokenAtAttempt = this.ports.getAccessToken();
+    const outcome = await this.refresh(isRetry ? "proactive-retry" : "proactive-timer");
     if (this.stopped) return;
+    if (outcome.kind === "transient") {
+      if (!isRetry) this.armProactiveRetry(accessTokenAtAttempt);
+      return;
+    }
     if (outcome.kind !== "success") return;
     if (this.ports.onProactiveRefreshed) {
       try {
@@ -352,6 +379,50 @@ export class RefreshManager {
     }
   }
 
+  /**
+   * §B — arm the one-shot retry, measured from the failed attempt's start
+   * (`lastAttemptAt`). It runs through `refresh()`, so single-flight dedupe, the
+   * rejected-token latch and the min-interval floor all still apply. It is
+   * skipped when the access token changed meanwhile (someone else rotated).
+   */
+  private armProactiveRetry(accessTokenAtAttempt: string): void {
+    this.clearProactiveRetry();
+    const rawJitter = (this.ports.proactiveRetryJitter ?? defaultProactiveRetryJitter)();
+    const jitterMs = Math.min(
+      PROACTIVE_RETRY_JITTER_MAX_MS,
+      Math.max(PROACTIVE_RETRY_JITTER_MIN_MS, rawJitter),
+    );
+    const dueAtMs = this.lastAttemptAt + MIN_REFRESH_INTERVAL_MS + jitterMs;
+    const delayMs = Math.max(0, dueAtMs - this.now());
+    this.ports.log?.info?.(
+      `clawchat-plugin-openclaw proactive refresh transient; one-shot retry in ${delayMs}ms`,
+    );
+    this.proactiveRetryTimer = this.setTimer(() => {
+      this.proactiveRetryTimer = null;
+      if (this.stopped) return;
+      if (this.ports.getAccessToken() !== accessTokenAtAttempt) {
+        this.ports.log?.debug?.(
+          "clawchat-plugin-openclaw proactive retry skipped (access token already changed)",
+        );
+        return;
+      }
+      void this.runProactiveRefresh(true);
+    }, delayMs);
+  }
+
+  private clearProactiveRetry(): void {
+    if (this.proactiveRetryTimer != null) {
+      this.clearTimer(this.proactiveRetryTimer);
+      this.proactiveRetryTimer = null;
+    }
+  }
+
+  /**
+   * Clear the proactive `refresh_at` timer (called on WS disconnect). The §B
+   * one-shot retry is deliberately NOT cleared here: a refresh timeout usually
+   * coincides with the network drop that also closes the socket, and refresh
+   * does not need the socket. `stop()` clears both.
+   */
   disarmProactiveTimer(): void {
     if (this.proactiveTimer != null) {
       this.clearTimer(this.proactiveTimer);
@@ -377,10 +448,11 @@ export class RefreshManager {
     return this.now() >= refreshAtMs;
   }
 
-  /** Stop the manager — clears the proactive timer; no further refreshes arm. */
+  /** Stop the manager — clears the proactive + retry timers; nothing further arms. */
   stop(): void {
     this.stopped = true;
     this.disarmProactiveTimer();
+    this.clearProactiveRetry();
   }
 
   /** Test/inspection seam — the latched (rejected) access token, if any. */
@@ -435,3 +507,10 @@ function decodeJwtIat(token: string): number | null {
 function defaultJitter(): number {
   return (Math.random() * 2 - 1) * PROACTIVE_JITTER_MS;
 }
+
+function defaultProactiveRetryJitter(): number {
+  return (
+    PROACTIVE_RETRY_JITTER_MIN_MS +
+    Math.random() * (PROACTIVE_RETRY_JITTER_MAX_MS - PROACTIVE_RETRY_JITTER_MIN_MS)
+  );
+}