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

package/src/login.runtime.ts

@@ -14,24 +14,16 @@ import {
   resolveOpenclawClawlingAccount,
 } from "./config.ts";
 import { getClawChatStore, type ClawChatStore } from "./storage.ts";
-
-/**
- * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
- * agent runtime — openclaw's bundled clawchat channel.
- */
-export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
-/**
- * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
- * always a bot; humans don't log in through this flow.
- */
-export const AGENTS_CONNECT_TYPE = "clawbot" as const;
-/**
- * `/v1/agents/connect` envelope code for "the supplied user_id matches no
- * agent". Servers that predate the server-side stale-user_id fallback return
- * this instead of degrading to a fresh pairing, so the client sheds the id and
- * retries once.
- */
-export const AGENT_NOT_FOUND_CODE = 16001 as const;
+import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
+import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.ts";
+// Re-exported: `src/login.runtime.test.ts` and `src/commands.ts` import these
+// from here, so the historical import path keeps working after the move.
+import {
+  AGENTS_CONNECT_PLATFORM,
+  AGENTS_CONNECT_TYPE,
+  AGENT_NOT_FOUND_CODE,
+} from "./onboarding-context.ts";
+export { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE };
 
 export type OpenclawClawchatMutateConfigFile = <T = void>(params: {
   afterWrite: { mode: "auto" } | { mode: "none" | "restart"; reason: string };
@@ -103,9 +95,11 @@ export class ExistingActivationError extends Error {
         "spent. Re-run stating the intent:\n" +
         "  - Pair as a BRAND-NEW agent (this instance stops using the identity " +
         "above): /clawchat-activate <CODE> --new-account\n" +
-        "  - RESTORE the identity above (re-pairs that same agent; if it was " +
-        "deleted this brings it back with its history): " +
-        "/clawchat-activate <CODE> --repair\n" +
+        "  - RESTORE the identity above: do not spend a fresh code on it. Ask your " +
+        "owner to send you the reconnect prompt from the ClawChat app — its code is " +
+        "bound to this identity and usually restores it on its own; if activation " +
+        "still reports it as already paired, run it again with --repair " +
+        `(/clawchat-activate <CODE> --repair) — and follow ${RECONNECT_GUIDE_URL}\n` +
         "  - To run a SECOND agent alongside this one instead, activate it as a " +
         "named account: /clawchat-activate <CODE> --account <name>  (or: openclaw " +
         "channels add --channel clawchat-plugin-openclaw --account <name> --token <CODE>)",
@@ -289,7 +283,63 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // overridden them, so login works without a prior `openclaw channels setup --channel clawchat-plugin-openclaw`.
   const account = resolveOpenclawClawlingAccount(cfg, accountId);
 
-  // Fork before the invite code is even read, so neither branch spends the code
+  const inviteCode = (
+    await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
+  ).trim();
+  if (!inviteCode) {
+    throw new Error("Login aborted: invite code is required.");
+  }
+
+  const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
+    baseUrl: account.baseUrl,
+    mediaBaseUrl: account.mediaBaseUrl,
+    // Pre-login we may not have a token yet. Send the current one (or empty)
+    // — the server should accept an unauthenticated invite-code exchange.
+    token: account.token || "",
+    pluginVersion: resolvePluginVersion(),
+  });
+
+  // Telemetry the backend joins with wiki field reports; ignored by older servers.
+  const onboarding = buildOnboardingContext();
+
+  // Non-consuming pre-check. `null` = endpoint unavailable, carry on. A bound
+  // code (the owner's reconnect prompt) is the owner's own proof of intent, so
+  // it settles the "new agent or restore?" question below without a flag.
+  //
+  // The pre-check only carries the `user_id` that `/connect` would replay. An
+  // explicit `newAccount` never replays it, so it must not be judged against
+  // it either: the server marks `pairable:false` for an `owner_mismatch` /
+  // `invalid` id, and that would block the very escape the refusal recommends.
+  const storedUserId = account.userId.trim();
+  const precheckUserId = params.newAccount ? "" : storedUserId;
+  runtime.log("Checking the invite code …");
+  let precheck = await preCheckConnectCode(
+    apiClient,
+    { code: inviteCode, userId: precheckUserId || undefined, context: onboarding },
+    runtime.log,
+  );
+  // Whether the operator will be asked "new agent or restore?" below. When
+  // they will, a refusal caused only by the stored identity (not by the code)
+  // is deferred: choosing a brand-new identity drops that id, so the verdict
+  // on it no longer applies.
+  const identityUnsettled =
+    storedUserId !== "" && account.token.trim() !== "" && !params.newAccount && !params.repair;
+  const refusedForIdentity =
+    precheck !== null &&
+    !precheck.pairable &&
+    precheckUserId !== "" &&
+    // Only a live code: a dead one (expired / paired / invalid) refuses on its
+    // own account whatever identity is chosen, so there is nothing to defer.
+    precheck.status === "pending" &&
+    (precheck.userIdStatus === "owner_mismatch" || precheck.userIdStatus === "invalid");
+  const deferredRefusal = identityUnsettled && refusedForIdentity ? precheck : null;
+  if (precheck && !precheck.pairable && !deferredRefusal) {
+    throw new Error(unpairableMessage(precheck));
+  }
+  const boundToIncumbent =
+    precheck?.pairable === true && precheck.boundAgent === true && precheckUserId !== "";
+
+  // Fork before the invite code is spent, so neither branch spends the code
   // before the outcome is settled. "Live" is decided by whether a usable token
   // remains: auto-logout (§C) blanks the tokens but preserves the identity, so a
   // logged-out instance still re-pairs with no flag at all, which is the flow
@@ -299,50 +349,60 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // ambiguous, because redeeming a code here can either mint a new agent or
   // re-pair the incumbent one. Ask which, and only refuse when nobody answers.
   // An explicit `newAccount` / `repair` from the caller has already settled it,
-  // so no prompt.
+  // so no prompt. Nor is one needed when the pre-check proved the code is the
+  // owner's own reconnect prompt for this very agent (`boundToIncumbent`) — a
+  // bound code can only ever restore the incumbent identity.
   let newAccount = params.newAccount;
-  if (account.userId.trim() && account.token.trim() && !newAccount && !params.repair) {
+  if (identityUnsettled && !boundToIncumbent) {
     const identity = account.agentId.trim()
-      ? `agent ${account.agentId.trim()} (shadow user ${account.userId.trim()})`
-      : `agent ${account.userId.trim()}`;
+      ? `agent ${account.agentId.trim()} (shadow user ${storedUserId})`
+      : `agent ${storedUserId}`;
     const intent = await (params.readActivationIntent ??
       (() => promptActivationIntentFromStdin(runtime, identity)))();
     // Only "new-account" changes what gets sent. Restoring needs no flag:
     // replaying the stored `user_id` IS the re-pair, and that is already the
     // default below — so choosing it simply means "don't refuse".
-    if (intent === "new-account") newAccount = true;
-    else if (intent === null) {
-      throw new ExistingActivationError(account.userId.trim(), account.agentId.trim());
+    if (intent === "new-account") {
+      newAccount = true;
+      if (deferredRefusal) {
+        // The first verdict judged the id we are now dropping; re-check the
+        // code on its own before spending it.
+        precheck = await preCheckConnectCode(
+          apiClient,
+          { code: inviteCode, context: onboarding },
+          runtime.log,
+        );
+        if (precheck && !precheck.pairable) {
+          throw new Error(unpairableMessage(precheck));
+        }
+      }
+    } else if (deferredRefusal) {
+      // Restoring (or nobody to ask) replays the id the server already refused.
+      throw new Error(unpairableMessage(deferredRefusal));
+    } else if (intent === null) {
+      throw new ExistingActivationError(storedUserId, account.agentId.trim());
     }
   }
 
-  const inviteCode = (
-    await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
-  ).trim();
-  if (!inviteCode) {
-    throw new Error("Login aborted: invite code is required.");
+  // A new identity (flag or interactive choice) sends no user_id, and /connect
+  // without one on a bound code silently RESTORES the bound agent and spends
+  // the code. A reconnect code can never mint an agent, so refuse first.
+  if (newAccount && precheck?.boundAgent === true) {
+    throw new Error(boundCodeNewIdentityMessage());
   }
 
-  const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
-    baseUrl: account.baseUrl,
-    mediaBaseUrl: account.mediaBaseUrl,
-    // Pre-login we may not have a token yet. Send the current one (or empty)
-    // — the server should accept an unauthenticated invite-code exchange.
-    token: account.token || "",
-    pluginVersion: resolvePluginVersion(),
-  });
-
   runtime.log("Verifying invite code …");
   let result;
   // A brand-new identity is precisely "do not replay" — the replay is the only
   // thing that would bind this code to the incumbent agent.
-  const existingUserId = newAccount ? "" : account.userId.trim();
+  const existingUserId = newAccount ? "" : storedUserId;
   try {
     result = await apiClient.agentsConnect({
       code: inviteCode,
       platform: AGENTS_CONNECT_PLATFORM,
       type: AGENTS_CONNECT_TYPE,
       ...(existingUserId ? { user_id: existingUserId } : {}),
+      context: onboarding,
     });
   } catch (err) {
     if (err instanceof ClawlingApiError) {
@@ -363,6 +423,7 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
+            context: onboarding,
           });
         } catch (retryErr) {
           if (retryErr instanceof ClawlingApiError) {

package/src/onboarding-context.ts

@@ -0,0 +1,77 @@
+/**
+ * Onboarding telemetry the plugin attaches to `/v1/agents/connect` and
+ * `/v1/agents/connect/check` (all optional, all ignored by older backends).
+ *
+ * Values mirror the connection wiki's manifest vocabulary so the backend can
+ * join plugin activations with wiki field reports without an alias table:
+ *   - `agent_kind` = the wiki `match.agent` name for this host
+ *   - `lane`       = "self": this plugin holds its own WebSocket + token
+ *   - `matched_install` = the wiki page slug that routes to this plugin
+ * Nothing here is a credential and nothing here gates activation.
+ */
+
+export const AGENT_KIND = "openclaw" as const;
+export const LANE = "self" as const;
+export const MATCHED_INSTALL = "install/official-openclaw" as const;
+
+/** Public connection wiki. `/start.md` is the entry page; `/reconnect.md` the re-pair page. */
+export const START_GUIDE_URL = "https://agent-connection.clawling.com/start.md" as const;
+export const RECONNECT_GUIDE_URL = "https://agent-connection.clawling.com/reconnect.md" as const;
+
+const WIKI_VERSION_MAX = 40;
+
+/** Wiki `os` enum (windows | macos | linux); "" for anything else so callers omit it. */
+export function hostOs(plat: string = process.platform): "windows" | "macos" | "linux" | "" {
+  switch (plat) {
+    case "win32":
+      return "windows";
+    case "darwin":
+      return "macos";
+    case "linux":
+      return "linux";
+    default:
+      return "";
+  }
+}
+
+/**
+ * The wiki build stamp the agent saw on the install page. The official install
+ * page tells the agent to export `CLAWCHAT_WIKI_VERSION` before activating; a
+ * hand-run `openclaw channels add` simply has none.
+ */
+export function wikiVersion(env: NodeJS.ProcessEnv = process.env): string {
+  return (env.CLAWCHAT_WIKI_VERSION ?? "").trim().slice(0, WIKI_VERSION_MAX);
+}
+
+export function buildOnboardingContext(
+  opts: { platform?: string; env?: NodeJS.ProcessEnv } = {},
+): Record<string, string> {
+  const out: Record<string, string> = {
+    agent_kind: AGENT_KIND,
+    lane: LANE,
+    matched_install: MATCHED_INSTALL,
+  };
+  const os = hostOs(opts.platform);
+  if (os) out.os = os;
+  const wiki = wikiVersion(opts.env);
+  if (wiki) out.wiki_version = wiki;
+  return out;
+}
+
+/**
+ * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
+ * agent runtime — openclaw's bundled clawchat channel.
+ */
+export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
+/**
+ * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
+ * always a bot; humans don't log in through this flow.
+ */
+export const AGENTS_CONNECT_TYPE = "clawbot" as const;
+/**
+ * `/v1/agents/connect` envelope code for "the supplied user_id matches no
+ * agent". Servers that predate the server-side stale-user_id fallback return
+ * this instead of degrading to a fresh pairing, so the client sheds the id and
+ * retries once.
+ */
+export const AGENT_NOT_FOUND_CODE = 16001 as const;

package/src/onboarding-report.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Optional onboarding facts the AGENT writes after following the connection
+ * wiki: the id of the field report it filed there, and its self-assessed
+ * capability tier. The plugin only relays them on the plugin-report call; it
+ * never files a wiki report itself. Same directory as the greeting override
+ * (`~/clawchat/`), so the agent already knows the place.
+ */
+export interface OnboardingReportFields {
+  wiki_report_id?: string;
+  capability_tier?: number;
+  capability_ceiling?: number;
+  capabilities?: { headless?: boolean; mcp?: boolean; permission_hook?: boolean; session_line?: boolean };
+}
+
+const REPORT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const CAP_KEYS = ["headless", "mcp", "permission_hook", "session_line"] as const;
+
+function tier(v: unknown): number | undefined {
+  return Number.isInteger(v) && (v as number) >= 1 && (v as number) <= 4 ? (v as number) : undefined;
+}
+
+/**
+ * Read + validate `~/clawchat/onboarding.json`. Never throws: an unresolvable
+ * home directory, an absent/unreadable file, or malformed JSON all fall
+ * through to `null`, same as a file with no valid fields — this must be safe
+ * to call unconditionally from a best-effort report path.
+ */
+export function readOnboardingReport(homeDir?: string): OnboardingReportFields | null {
+  try {
+    const base = homeDir ?? os.homedir();
+    const file = path.join(base, "clawchat", "onboarding.json");
+    const raw: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const o = raw as Record<string, unknown>;
+    const out: OnboardingReportFields = {};
+    if (typeof o.wiki_report_id === "string" && REPORT_ID_RE.test(o.wiki_report_id)) out.wiki_report_id = o.wiki_report_id;
+    const t = tier(o.capability_tier);
+    if (t !== undefined) out.capability_tier = t;
+    const c = tier(o.capability_ceiling);
+    // The backend rejects the WHOLE report (22004) when ceiling < tier, which
+    // would silently stop the version row updating. Keep the tier, drop the
+    // inconsistent ceiling.
+    if (c !== undefined && (t === undefined || c >= t)) out.capability_ceiling = c;
+    if (o.capabilities && typeof o.capabilities === "object") {
+      const caps: NonNullable<OnboardingReportFields["capabilities"]> = {};
+      for (const k of CAP_KEYS) {
+        const v = (o.capabilities as Record<string, unknown>)[k];
+        if (typeof v === "boolean") caps[k] = v;
+      }
+      if (Object.keys(caps).length > 0) out.capabilities = caps;
+    }
+    return Object.keys(out).length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}

package/src/plugin-report.ts

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import type { OnboardingReportFields } from "./onboarding-report.ts";
 
 const PACKAGE_NAME = "@clawling/clawchat-plugin-openclaw";
 
@@ -48,6 +49,8 @@ export interface ReportParams {
   pluginVersion: string;
   agentVersion: string;
   authenticated: boolean;
+  /** Agent-written onboarding facts (`~/clawchat/onboarding.json`); optional. */
+  onboarding?: OnboardingReportFields | null;
   log?: { debug?: (msg: string) => void };
 }
 
@@ -70,6 +73,7 @@ export async function reportPluginVersionSafe(p: ReportParams): Promise<void> {
         agentVersion: p.agentVersion,
         runtimeName: "node",
         runtimeVersion: process.version,
+        onboarding: p.onboarding ?? null,
       },
       { authenticated: p.authenticated },
     );

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)
+  );
+}