@clawling/clawchat-plugin-openclaw 2026.6.30-4 → 2026.7.1

package/src/api-client.ts

@@ -17,6 +17,7 @@ import {
   type UserSearchHit,
 } from "./api-types.ts";
 import type { GroupSettings, GroupSettingsFetchResult } from "./group-settings.ts";
+import type { PermissionPolicy, PermState } from "./permissions.ts";
 import { CHANNEL_ID } from "./config.ts";
 
 export interface PluginReportInput {
@@ -179,6 +180,17 @@ export interface OpenclawClawlingApiClient {
    * error still throws.
    */
   getMyGroupSettings(): Promise<GroupSettingsFetchResult>;
+  /**
+   * Fetch the agent's permission policy from `GET /v1/agents/me/permissions`.
+   *
+   * The response `data` is a flat object mapping operation name → state
+   * (`"ask"|"allow"|"deny"`), with one special key `"moment.visibility"` whose
+   * value is a string array. Returns a `PermissionPolicy` with `byOperation`
+   * (all non-visibility keys) and `momentVisibility` (the array). Throws on
+   * network errors or non-2xx responses; callers must catch and keep the stale
+   * cache (never throw / never block message handling).
+   */
+  getMyPermissions(): Promise<PermissionPolicy>;
   registerApp(params: { name: string; appId: string; url: string }): Promise<{ app: AgentAppView }>;
   listApps(): Promise<{ apps: AgentAppView[] }>;
   unregisterApp(appId: string): Promise<{ deleted: boolean }>;
@@ -362,6 +374,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
           code,
           status: res.status,
           path,
+          ...(env.data !== undefined ? { data: env.data } : {}),
         });
       }
       return env.data as T;
@@ -759,5 +772,15 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       }
       return { authoritative: true, rows };
     },
+    async getMyPermissions(): Promise<PermissionPolicy> {
+      const data = await call<Record<string, unknown>>("GET", "/v1/agents/me/permissions");
+      const byOperation: Record<string, PermState> = {};
+      let momentVisibility: string[] = [];
+      for (const [k, v] of Object.entries(data ?? {})) {
+        if (k === "moment.visibility") momentVisibility = (v as string[]) ?? [];
+        else byOperation[k] = v as PermState;
+      }
+      return { byOperation, momentVisibility };
+    },
   };
 }

package/src/api-types.ts

@@ -157,7 +157,7 @@ export class ClawlingApiError extends Error {
   constructor(
     public readonly kind: ClawlingApiErrorKind,
     message: string,
-    public readonly meta?: { code?: number; status?: number; path?: string },
+    public readonly meta?: { code?: number; status?: number; path?: string; data?: unknown },
   ) {
     super(message);
     this.name = "ClawlingApiError";

package/src/config.ts

@@ -106,6 +106,8 @@ export type OpenclawClawlingConfig = {
   forwardToolCalls?: boolean;
   /** Emit approval/action rich fragments instead of plain fallback text. */
   richInteractions?: boolean;
+  /** Emit ONE consolidated awareness note to the agent when friend/conversation signals arrive. */
+  awarenessNote?: boolean;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -152,6 +154,7 @@ export const openclawClawlingConfigSchema = {
     forwardThinking: { type: "boolean" },
     forwardToolCalls: { type: "boolean" },
     richInteractions: { type: "boolean" },
+    awarenessNote: { type: "boolean" },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -274,6 +277,7 @@ export type ResolvedOpenclawClawlingAccount = {
   forwardThinking: boolean;
   forwardToolCalls: boolean;
   richInteractions: boolean;
+  awarenessNote: boolean;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -482,6 +486,8 @@ export function resolveOpenclawClawlingAccount(
     typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
   const richInteractions =
     typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
+  const awarenessNote =
+    typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
 
   return {
     accountId: DEFAULT_ACCOUNT_ID,
@@ -508,6 +514,7 @@ export function resolveOpenclawClawlingAccount(
     forwardThinking,
     forwardToolCalls,
     richInteractions,
+    awarenessNote,
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),

package/src/friend-request-turn.ts

@@ -0,0 +1,87 @@
+/**
+ * Synthetic reasoning-turn builder for `friend.request` notify.signal events.
+ *
+ * When the server fires a `friend.request` signal the runtime dispatches one
+ * deduped synthetic `message.send` envelope so the agent can reason about the
+ * pending request. The prompt text varies by the current "friend.add" permission
+ * policy state: a deny policy yields a decline/inform prompt; ask or allow
+ * yields a prompt that instructs the agent to review the request via the
+ * `clawchat_list_friend_requests` tool.
+ */
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { PermState } from "./permissions.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+/**
+ * Returns canned prompt text for a friend-request reasoning turn based on the
+ * current "friend.add" permission policy state.
+ *
+ * - `deny`  → inform the agent it should decline; no accept instruction.
+ * - `ask` / `allow` → instruct the agent to review the pending request.
+ */
+export function friendRequestPromptFor(state: PermState): string {
+  if (state === "deny") {
+    return [
+      "A new friend request has arrived.",
+      "Your current friend-add policy is set to deny.",
+      "Do not add this contact.",
+      "You may inform the requester that you cannot add them at this time.",
+    ].join(" ");
+  }
+  return [
+    "A new friend request has arrived.",
+    "Please review the pending request by calling `clawchat_list_friend_requests`",
+    "and decide whether to accept it.",
+  ].join(" ");
+}
+
+export interface BuildFriendRequestEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /** Current "friend.add" permission policy state. */
+  state: PermState;
+  /** entity_id from the notify.signal payload (the requesting user). */
+  entityId: string;
+}
+
+/**
+ * Builds a synthetic `message.send` envelope that triggers one agent reasoning
+ * turn for a pending friend request. The envelope shape mirrors the
+ * activation-bootstrap envelope; it targets the owner's direct conversation so
+ * the agent has context about who it is reasoning for.
+ */
+export function buildFriendRequestEnvelope(
+  params: BuildFriendRequestEnvelopeParams,
+): Envelope {
+  const { account, state, entityId } = params;
+  const text = friendRequestPromptFor(state);
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
+    emitted_at: now,
+    chat_id: account.ownerUserId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-friend-request",
+      type: "direct",
+      nick_name: "ClawChat",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${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,
+        },
+      },
+    },
+  };
+}

package/src/gate-outcome.ts

@@ -0,0 +1,44 @@
+/**
+ * Maps backend owner-approval gate codes to structured tool outcomes.
+ *
+ * Backend gate codes (confirmed live contract):
+ *   21001 — pending owner approval (payload: { request_id, operation, expires_at })
+ *   21003 — policy forbidden       (payload: { operation })
+ *
+ * Returns null for any other code so callers can fall through to normal handling.
+ */
+
+export type PendingApprovalOutcome = {
+  status: "pending_owner_approval";
+  request_id: string;
+  operation: string;
+  expires_at: number;
+};
+
+export type ForbiddenOutcome = {
+  status: "forbidden_by_owner";
+  operation: string;
+};
+
+export type GateOutcome = PendingApprovalOutcome | ForbiddenOutcome;
+
+export function mapGateOutcome(
+  code: number,
+  data: Record<string, unknown>,
+): GateOutcome | null {
+  if (code === 21001) {
+    return {
+      status: "pending_owner_approval",
+      request_id: typeof data.request_id === "string" ? data.request_id : "",
+      operation: typeof data.operation === "string" ? data.operation : "",
+      expires_at: typeof data.expires_at === "number" ? data.expires_at : 0,
+    };
+  }
+  if (code === 21003) {
+    return {
+      status: "forbidden_by_owner",
+      operation: typeof data.operation === "string" ? data.operation : "",
+    };
+  }
+  return null;
+}

package/src/inbound.ts

@@ -8,6 +8,7 @@ import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 import type { MediaItem } from "./media-runtime.ts";
 import { extractMediaFragments, fragmentsToText, type MentionedUser } from "./message-mapper.ts";
 import { hasRenderableText, isInboundMessagePayload } from "./protocol.ts";
+import type { PermissionResultMetadata } from "./permission-result.ts";
 
 export interface IngestTurnParams {
   channel: "clawchat-plugin-openclaw";
@@ -81,6 +82,20 @@ export interface DispatchInboundParams {
     text: string;
     chatId: string;
   }) => Promise<boolean>;
+  /**
+   * Optional consumer for `permission_result` system-message receipts.
+   *
+   * When `sender.id === "system"` and `payload.metadata.kind ===
+   * "permission_result"`, the guard calls this callback with the metadata
+   * object instead of performing the generic system-message drop. The
+   * callback is responsible for deduplication and synthetic-turn dispatch
+   * (see `src/permission-result.ts`).
+   *
+   * When absent, `permission_result` frames fall through to the existing
+   * system-message drop (safe default — no regression for callers that have
+   * not yet wired the consumer).
+   */
+  consumePermissionResult?: (metadata: PermissionResultMetadata) => Promise<void>;
   log?: { info?: (m: string) => void; error?: (m: string) => void };
 }
 
@@ -241,6 +256,19 @@ export async function dispatchOpenclawClawlingInbound(
     return;
   }
   if (sender.id === "system") {
+    // Intercept `permission_result` receipts before the generic system-message
+    // drop. The discriminator is `payload.metadata.kind === "permission_result"`;
+    // all other system messages (group-join notifications, etc.) still drop.
+    const rawPayload = envelope.payload as Record<string, unknown>;
+    const meta = rawPayload.metadata as Record<string, unknown> | undefined;
+    if (
+      params.consumePermissionResult &&
+      meta != null &&
+      meta.kind === "permission_result"
+    ) {
+      await params.consumePermissionResult(meta as unknown as PermissionResultMetadata);
+      return;
+    }
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip system message msg=${payload.message_id}`,
     );

package/src/permission-result.ts

@@ -0,0 +1,128 @@
+/**
+ * Consumer for `permission_result` system-message receipts.
+ *
+ * When the backend delivers a `permission_result` outcome as a
+ * `message.send` system frame (`sender.id="system"`, `payload.metadata.kind
+ * ="permission_result"`), this module deduplicates by `request_id` and
+ * produces a synthetic context-note turn so the agent can close the loop
+ * on the original permission request.
+ *
+ * Wire shape (authoritative):
+ * ```
+ * payload.metadata = {
+ *   kind: "permission_result",
+ *   operation: "friend.add",
+ *   outcome: "approved" | "denied" | "expired" | "failed",
+ *   reason: "owner_allowed" | …,
+ *   request_id: "prq_…",
+ * }
+ * ```
+ * The discriminator is `payload.metadata.kind === "permission_result"`.
+ */
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export interface PermissionResultMetadata {
+  kind: "permission_result";
+  operation: string;
+  outcome: "approved" | "denied" | "expired" | "failed";
+  reason: string;
+  request_id: string;
+}
+
+// Module-level dedup set — `request_id` values are stable backend identifiers.
+// A duplicate receipt (e.g. from WS replay on reconnect) must not re-trigger
+// an agent turn.
+const _seenRequestIds = new Set<string>();
+
+/**
+ * @internal Test helper — reset the dedup set between isolated test runs.
+ * Never call this in production code.
+ */
+export function _resetPermissionResultDedup(): void {
+  _seenRequestIds.clear();
+}
+
+function buildOutcomeNote(metadata: PermissionResultMetadata): string {
+  const { operation, outcome, reason } = metadata;
+  const outcomeLabel =
+    outcome === "approved"
+      ? "approved"
+      : outcome === "denied"
+        ? "denied"
+        : outcome === "expired"
+          ? "expired"
+          : "failed";
+  const resolution =
+    outcome === "approved"
+      ? "The requested action has been completed."
+      : "No further action was taken.";
+  return [
+    `Permission request for operation "${operation}" has been ${outcomeLabel}.`,
+    `Reason: ${reason}.`,
+    resolution,
+  ].join(" ");
+}
+
+/**
+ * Builds a synthetic `message.send` envelope that delivers a
+ * `permission_result` context note to the agent.
+ *
+ * Mirrors the `buildFriendRequestEnvelope` pattern: a synthetic inbound
+ * `message.send` targeting the owner's direct conversation, routed through
+ * `handleInboundEnvelope` so the agent can reason about the outcome.
+ */
+export function buildPermissionResultEnvelope(params: {
+  account: Pick<ResolvedOpenclawClawlingAccount, "userId" | "ownerUserId">;
+  metadata: PermissionResultMetadata;
+}): Envelope {
+  const { account, metadata } = params;
+  const text = buildOutcomeNote(metadata);
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${now}`,
+    emitted_at: now,
+    chat_id: account.ownerUserId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-permission-result",
+      type: "direct",
+      nick_name: "ClawChat",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${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,
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Handles a `permission_result` receipt. Deduplicates by `request_id`
+ * (idempotent — WS replay on reconnect may deliver the same receipt again).
+ *
+ * Returns a synthetic context-note {@link Envelope} on a fresh receipt so
+ * the caller can feed it to `handleInboundEnvelope`; returns `null` when
+ * the `request_id` has already been processed.
+ */
+export function handlePermissionResult(
+  metadata: PermissionResultMetadata,
+  account: Pick<ResolvedOpenclawClawlingAccount, "userId" | "ownerUserId">,
+): Envelope | null {
+  if (_seenRequestIds.has(metadata.request_id)) return null;
+  _seenRequestIds.add(metadata.request_id);
+  return buildPermissionResultEnvelope({ account, metadata });
+}

package/src/permissions.ts

@@ -0,0 +1,13 @@
+export type PermState = "ask" | "allow" | "deny";
+
+export interface PermissionPolicy {
+  byOperation: Record<string, PermState>;
+  momentVisibility: string[];
+}
+
+export class PermissionCache {
+  private p: PermissionPolicy = { byOperation: {}, momentVisibility: [] };
+  get(): PermissionPolicy { return this.p; }
+  set(p: PermissionPolicy): void { this.p = p; }
+  stateOf(op: string): PermState { return this.p.byOperation[op] ?? "ask"; }
+}

package/src/runtime.ts

@@ -78,6 +78,9 @@ import {
 import { createGroupMessageCoalescer } from "./group-message-coalescer.ts";
 import { openclawLlmContextDebug } from "./llm-context-debug.ts";
 import { GroupSettingsCache } from "./group-settings.ts";
+import { PermissionCache } from "./permissions.ts";
+import { buildFriendRequestEnvelope } from "./friend-request-turn.ts";
+import { handlePermissionResult } from "./permission-result.ts";
 
 type Log = { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
 type ChannelContextBuilder = (params: Record<string, unknown>) => unknown;
@@ -1752,6 +1755,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     context: wsLogContext,
   });
   const groupSettingsCache = new GroupSettingsCache();
+  const permissionCache = new PermissionCache();
   // Findings 2 & 3 — gate group dispatch on the IN-FLIGHT settings pull, not just
   // the first one. The pull is fire-and-forget, so replayed/live group messages
   // could otherwise enter the governance gate against a stale/empty cache
@@ -1829,6 +1833,28 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }
     })();
   };
+  // Best-effort pull of the agent's permission policy from the backend.
+  // Called at startup (bypassRefresh: true, mirrors pullGroupSettings startup)
+  // and on every successful (re)connect after hello-ok. On failure, logs and
+  // keeps the stale cache — never throws, never blocks message handling.
+  const pullPermissions = (opts?: { bypassRefresh?: boolean }): void => {
+    void (async () => {
+      try {
+        const policy = opts?.bypassRefresh
+          ? await (conversationApiClient ??= buildConversationApiClient()).getMyPermissions()
+          : await getConversationApiClient().getMyPermissions();
+        permissionCache.set(policy);
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw permissions pull ok ops=${Object.keys(policy.byOperation).length}`,
+        );
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw permissions pull failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        // Keep stale cache; never throw.
+      }
+    })();
+  };
   const logAuthFailure = (reason: string) => {
     if (authFailureLogged) return;
     authFailureLogged = true;
@@ -1962,6 +1988,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       // Re-pull per-group agent settings on every successful (re)connect so the
       // cache stays current after a network interruption or token refresh.
       pullGroupSettings();
+      // Re-pull permission policy alongside group settings on every (re)connect.
+      pullPermissions();
       // §A.1 — arm the proactive refresh timer from the live token's `exp`
       // every time a connection becomes ready (re-armed after every refresh via
       // the gateway re-enter).
@@ -2193,6 +2221,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     });
   };
 
+  // Debounce flag for lighter-awareness consolidated notes.
+  // A single queueMicrotask coalesces all awareness signals that arrive in
+  // the same synchronous turn into exactly one handleInboundEnvelope call.
+  let pendingAwarenessNote = false;
+
   client.on("notify:signal", (env: Envelope) => {
     // §9.4 reliable system notification. The plugin holds no friend/roster
     // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -2204,11 +2237,17 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         ? (env.payload as Record<string, unknown>)
         : undefined;
       const type = typeof payload?.type === "string" ? payload.type : "";
+      const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
       if (type === "agent.config.changed") {
         log?.info?.(
           `[${accountId}] clawchat-plugin-openclaw agent.config.changed signal received; re-pulling group settings`,
         );
         pullGroupSettings();
+      } else if (type === "agent.permission.changed") {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw agent.permission.changed signal received; re-pulling permissions`,
+        );
+        pullPermissions();
       } else if (type === "clawchat.skill.update.check") {
         // Content-free trigger: check the official skill source in code and, if
         // there is an update, ask the owner in chat for consent. The atomic
@@ -2223,6 +2262,66 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             }`,
           );
         });
+      } else if (type === "friend.request") {
+        // Dedup is already applied above by notifySignalObserver.observe (the live
+        // frame and its reliable-inbox replay share the same event_id and collapse
+        // to one observation). Build one synthetic reasoning turn so the agent can
+        // act on the pending request; the prompt text varies by policy state.
+        const state = permissionCache.stateOf("friend.add");
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw friend.request signal received; dispatching reasoning turn entity_id=${entityId} policy=${state}`,
+        );
+        void handleInboundEnvelope(buildFriendRequestEnvelope({ account, state, entityId }));
+      } else if (
+        type === "friend.added" ||
+        type === "friend.removed" ||
+        type === "friend.profile_updated" ||
+        type.startsWith("conversation.")
+      ) {
+        // Lighter-awareness: log + optional single consolidated note. Never
+        // injects a full reasoning turn per event (unlike friend.request).
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw ${type} signal received; lighter-awareness handling`,
+        );
+        if (account.awarenessNote && !pendingAwarenessNote) {
+          pendingAwarenessNote = true;
+          queueMicrotask(() => {
+            pendingAwarenessNote = false;
+            const now = Date.now();
+            void handleInboundEnvelope({
+              version: "2",
+              event: EVENT.MESSAGE_SEND,
+              trace_id: `clawchat-plugin-openclaw-awareness-${now}`,
+              emitted_at: now,
+              chat_id: account.ownerUserId,
+              chat_type: "direct",
+              to: { id: account.userId, type: "direct" },
+              sender: { id: "clawchat-awareness", type: "direct", nick_name: "ClawChat" },
+              payload: {
+                message_id: `clawchat-plugin-openclaw-awareness-${now}`,
+                message_mode: "normal",
+                message: {
+                  body: {
+                    fragments: [
+                      {
+                        kind: "text",
+                        text: "ClawChat awareness: your contacts or conversations have been updated.",
+                      },
+                    ],
+                  },
+                  context: { mentions: [], reply: null },
+                  streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                  },
+                },
+              },
+            } as unknown as Envelope);
+          });
+        }
       }
     }
   });
@@ -2924,6 +3023,18 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         account,
         log,
         consumeOwnerConsent: consumeOwnerSkillConsent,
+        consumePermissionResult: async (metadata) => {
+          // A permission_result receipt closes the loop on an earlier request.
+          // Dedup by request_id; on a fresh receipt feed the synthetic context
+          // note back to the agent so it can react to the outcome.
+          const note = handlePermissionResult(metadata, account);
+          if (note) {
+            log?.info?.(
+              `[${accountId}] clawchat-plugin-openclaw permission_result receipt op=${metadata.operation} outcome=${metadata.outcome} request_id=${metadata.request_id}; dispatching context note`,
+            );
+            void handleInboundEnvelope(note);
+          }
+        },
         ingest: async (turn) => {
           ingestResult = await ingestTurn(turn);
         },
@@ -3020,6 +3131,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // rotating `account.token` out from under the already-constructed WS client.
   // Settling this releases the Finding-2 group-dispatch gate.
   pullGroupSettings({ bypassRefresh: true });
+  // Initial pull of permission policy at startup (best-effort; errors logged,
+  // stale cache kept). Uses bypassRefresh for the same reason as pullGroupSettings.
+  pullPermissions({ bypassRefresh: true });
   // Safety: never strand a held group message if the runtime is torn down while a
   // pull is in flight. `waitWithTimeout` already releases group waiters on abort,
   // but force the gate open too so any later `wait()` resolves immediately.