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

package/dist/src/api-client.js

@@ -196,6 +196,7 @@ export function createOpenclawClawlingApiClient(opts) {
                     code,
                     status: res.status,
                     path,
+                    ...(env.data !== undefined ? { data: env.data } : {}),
                 });
             }
             return env.data;
@@ -516,5 +517,17 @@ export function createOpenclawClawlingApiClient(opts) {
             }
             return { authoritative: true, rows };
         },
+        async getMyPermissions() {
+            const data = await call("GET", "/v1/agents/me/permissions");
+            const byOperation = {};
+            let momentVisibility = [];
+            for (const [k, v] of Object.entries(data ?? {})) {
+                if (k === "moment.visibility")
+                    momentVisibility = v ?? [];
+                else
+                    byOperation[k] = v;
+            }
+            return { byOperation, momentVisibility };
+        },
     };
 }

package/dist/src/config.js

@@ -81,6 +81,7 @@ export const openclawClawlingConfigSchema = {
         forwardThinking: { type: "boolean" },
         forwardToolCalls: { type: "boolean" },
         richInteractions: { type: "boolean" },
+        awarenessNote: { type: "boolean" },
         reconnect: {
             type: "object",
             additionalProperties: false,
@@ -328,6 +329,7 @@ export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
     const forwardThinking = typeof channel.forwardThinking === "boolean" ? channel.forwardThinking : true;
     const forwardToolCalls = 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,
         name: CHANNEL_ID,
@@ -353,6 +355,7 @@ export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
         forwardThinking,
         forwardToolCalls,
         richInteractions,
+        awarenessNote,
         allowFrom: [],
         reconnect: readReconnect(channel.reconnect),
         heartbeat: readHeartbeat(channel.heartbeat),

package/dist/src/friend-request-turn.js

@@ -0,0 +1,73 @@
+/**
+ * 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 } from "./protocol-types.js";
+/**
+ * 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) {
+    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(" ");
+}
+/**
+ * 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) {
+    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/dist/src/gate-outcome.js

@@ -0,0 +1,26 @@
+/**
+ * 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 function mapGateOutcome(code, data) {
+    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/dist/src/inbound.js

@@ -115,6 +115,17 @@ export async function dispatchOpenclawClawlingInbound(params) {
         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;
+        const meta = rawPayload.metadata;
+        if (params.consumePermissionResult &&
+            meta != null &&
+            meta.kind === "permission_result") {
+            await params.consumePermissionResult(meta);
+            return;
+        }
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw skip system message msg=${payload.message_id}`);
         return;
     }

package/dist/src/permission-result.js

@@ -0,0 +1,107 @@
+/**
+ * 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 } from "./protocol-types.js";
+// 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();
+/**
+ * @internal Test helper — reset the dedup set between isolated test runs.
+ * Never call this in production code.
+ */
+export function _resetPermissionResultDedup() {
+    _seenRequestIds.clear();
+}
+function buildOutcomeNote(metadata) {
+    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) {
+    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, account) {
+    if (_seenRequestIds.has(metadata.request_id))
+        return null;
+    _seenRequestIds.add(metadata.request_id);
+    return buildPermissionResultEnvelope({ account, metadata });
+}

package/dist/src/permissions.js

@@ -0,0 +1,6 @@
+export class PermissionCache {
+    p = { byOperation: {}, momentVisibility: [] };
+    get() { return this.p; }
+    set(p) { this.p = p; }
+    stateOf(op) { return this.p.byOperation[op] ?? "ask"; }
+}

package/dist/src/reply-dispatcher.js

@@ -296,6 +296,12 @@ export function createOpenclawClawlingReplyDispatcher(options) {
     let typingActive = false;
     let terminalReplySuppressed = false;
     let finalDeliverySeen = false;
+    // Count of outbound messages that were actually delivered to the target
+    // (a real, successful send — not a suppressed/duplicate/failed one). This is
+    // the reliable "did anything actually reach the user?" signal; host-side
+    // `counts.block`/`counts.final` only reflect what the agent emitted, not
+    // whether the send succeeded (a cancelled send still counts as a block).
+    let outboundDeliveredCount = 0;
     const outboundEventType = () => (replyCtx ? "message.reply" : "message.send");
     const outboundRaw = () => ({ target, replyCtx: replyCtx ?? null });
     const terminalSendScopeId = options.terminalSendScopeId ?? null;
@@ -502,6 +508,8 @@ export function createOpenclawClawlingReplyDispatcher(options) {
             log,
         });
         recordOutboundAck("message", messageId, result);
+        if (result)
+            outboundDeliveredCount += 1;
         log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw send complete to=${target.chatId}`);
         openclawLlmContextDebug.writeSnapshot({
             visibility: "host_event",
@@ -676,6 +684,7 @@ export function createOpenclawClawlingReplyDispatcher(options) {
     });
     return {
         dispatcher: base.dispatcher,
+        getOutboundDeliveredCount: () => outboundDeliveredCount,
         replyOptions: {
             ...base.replyOptions,
             sourceReplyDeliveryMode: "automatic",

package/dist/src/runtime.js

@@ -28,6 +28,9 @@ import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, }
 import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
 import { GroupSettingsCache } from "./group-settings.js";
+import { PermissionCache } from "./permissions.js";
+import { buildFriendRequestEnvelope } from "./friend-request-turn.js";
+import { handlePermissionResult } from "./permission-result.js";
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("clawchat-plugin-openclaw runtime not initialized");
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map();
@@ -1381,6 +1384,7 @@ export async function startOpenclawClawlingGateway(params) {
         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
@@ -1454,6 +1458,25 @@ export async function startOpenclawClawlingGateway(params) {
             }
         })();
     };
+    // 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) => {
+        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) => {
         if (authFailureLogged)
             return;
@@ -1474,10 +1497,11 @@ export async function startOpenclawClawlingGateway(params) {
     };
     let dispatchActivationBootstrap = async () => { };
     // Set by dispatchTurnToAgent when it dispatches the synthetic
-    // `clawchat-bootstrap` turn: true only if the agent actually produced a final
-    // outbound message (the greeting). The bootstrap dispatcher reads it to decide
-    // whether to mark the bootstrap sent or leave it pending for a later retry.
-    let bootstrapProducedFinal = false;
+    // `clawchat-bootstrap` turn: true only if the greeting was actually delivered
+    // (a real successful outbound send — block or final). The bootstrap dispatcher
+    // reads it to decide whether to mark the bootstrap sent or leave it pending for
+    // a later retry.
+    let bootstrapGreetingDelivered = false;
     // Per-connection retry for a pending activation bootstrap (see the module-level
     // constants). Re-attempts on the live connection while `wsReady`, bounded by
     // ACTIVATION_BOOTSTRAP_MAX_RETRIES; the budget resets on each fresh connect.
@@ -1584,6 +1608,8 @@ export async function startOpenclawClawlingGateway(params) {
             // 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).
@@ -1795,6 +1821,10 @@ export async function startOpenclawClawlingGateway(params) {
             },
         });
     };
+    // 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) => {
         // §9.4 reliable system notification. The plugin holds no friend/roster
         // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -1806,10 +1836,15 @@ export async function startOpenclawClawlingGateway(params) {
                 ? env.payload
                 : 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
@@ -1819,6 +1854,62 @@ export async function startOpenclawClawlingGateway(params) {
                     log?.error?.(`[${accountId}] clawchat-plugin-openclaw skill-update check failed: ${err instanceof Error ? err.message : String(err)}`);
                 });
             }
+            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,
+                                    },
+                                },
+                            },
+                        });
+                    });
+                }
+            }
         }
     });
     client.on("replay:done", (env) => {
@@ -2166,7 +2257,7 @@ export async function startOpenclawClawlingGateway(params) {
                 chatType: turn.peer.kind,
                 agentId: route.agentId,
             });
-            const { dispatcher, replyOptions, markDispatchIdle } = createOpenclawClawlingReplyDispatcher({
+            const { dispatcher, replyOptions, markDispatchIdle, getOutboundDeliveredCount } = createOpenclawClawlingReplyDispatcher({
                 cfg,
                 runtime,
                 account,
@@ -2202,10 +2293,14 @@ export async function startOpenclawClawlingGateway(params) {
                 const counts = dispatchResult?.counts ?? {};
                 const queuedFinal = Boolean(dispatchResult?.queuedFinal);
                 if (turn.senderId === "clawchat-bootstrap") {
-                    // Did the agent actually emit a greeting? A final outbound message
-                    // means yes; block/tool-only (or nothing) means the greeting never
-                    // reached the user, so the bootstrap dispatcher will keep it pending.
-                    bootstrapProducedFinal = queuedFinal || (counts.final ?? 0) > 0;
+                    // Did the greeting actually reach the user? The reliable signal is a
+                    // real, successful outbound send (the agent may deliver the greeting
+                    // as a `block`, not a `final`, and a cancelled send still shows up in
+                    // host `counts.block`). Treat a queued/counted final as delivered too,
+                    // to cover deferred/human-delay finals not yet flushed at this point.
+                    const deliveredOutbound = getOutboundDeliveredCount?.() ?? 0;
+                    bootstrapGreetingDelivered =
+                        deliveredOutbound > 0 || queuedFinal || (counts.final ?? 0) > 0;
                 }
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`);
                 if (!queuedFinal && Object.values(counts).every((n) => !n)) {
@@ -2434,6 +2529,16 @@ export async function startOpenclawClawlingGateway(params) {
                 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);
                 },
@@ -2473,21 +2578,21 @@ export async function startOpenclawClawlingGateway(params) {
             const claimedBootstrap = bootstrap;
             claimedInFlight = true;
             incrementActivationBootstrapInFlight(accountId);
-            bootstrapProducedFinal = false;
+            bootstrapGreetingDelivered = false;
             const result = await handleInboundEnvelope(buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }));
             if (result !== "submitted") {
                 releaseBootstrap();
                 armBootstrapRetry();
                 return;
             }
-            // Only mark the bootstrap done once the agent has actually sent a greeting
-            // (a final outbound message). If the turn was handed off but produced no
-            // final reply — e.g. the greeting send was cancelled by a reconnect, or the
-            // agent went off to write a file/note instead of replying — leave the
+            // Only mark the bootstrap done once the greeting was actually delivered
+            // (a real successful outbound send). If the turn was handed off but nothing
+            // reached the user — e.g. the greeting send was cancelled by a reconnect, or
+            // the agent went off to write a file/note instead of replying — leave the
             // bootstrap pending (release the claim) and retry on the live connection,
             // rather than silently consuming it forever or waiting for the next reconnect.
-            if (!bootstrapProducedFinal) {
-                log?.info?.(`[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but produced no final reply; leaving pending for retry`);
+            if (!bootstrapGreetingDelivered) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw activation bootstrap dispatched but greeting was not delivered; leaving pending for retry`);
                 releaseBootstrap();
                 armBootstrapRetry();
                 return;
@@ -2520,6 +2625,9 @@ export async function startOpenclawClawlingGateway(params) {
     // 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.