@newbase-clawchat/openclaw-clawchat 2026.5.12-2 → 2026.5.12-21

package/src/runtime.ts

@@ -4,17 +4,25 @@ import {
   ProtocolError,
   StateError,
   TransportError,
-  type ClawlingChatClient,
+  EVENT,
   type Envelope,
   type Transport,
-} from "@newbase-clawchat/sdk";
+} from "./protocol-types.ts";
 import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
+import { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient } from "./client.ts";
-import { CHANNEL_ID, type ResolvedOpenclawClawlingAccount } from "./config.ts";
-import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError, type ConversationDetails } from "./api-types.ts";
+import {
+  CHANNEL_ID,
+  effectiveGroupCommandMode,
+  type ResolvedOpenclawClawlingAccount,
+} from "./config.ts";
+import type { ClawlingChatClient } from "./ws-client.ts";
+import { dispatchOpenclawClawlingInbound, type IngestTurnParams } from "./inbound.ts";
 import { fetchInboundMedia } from "./media-runtime.ts";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 import { sendStreamingText } from "./streaming.ts";
@@ -25,8 +33,47 @@ import {
 } from "./outbound.ts";
 import { formatWsLog } from "./ws-log.ts";
 import { createProtocolControlHandler, createReconnectTracker } from "./ws-alignment.ts";
+import {
+  clawChatDbPathForStateDir,
+  getClawChatStore,
+  type ClawChatStore,
+} from "./storage.ts";
+import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.ts";
+import {
+  loadClawChatPromptMetadata,
+  renderClawChatProfilePrompt,
+  resolveSenderRelation,
+} from "./profile-prompt.ts";
+import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.ts";
+import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.ts";
+import {
+  clearClawChatPromptInjectionForSession,
+  stageClawChatPromptInjection,
+} from "./prompt-injection.ts";
+import { createGroupMessageCoalescer } from "./group-message-coalescer.ts";
 
 type Log = { info?: (m: string) => void; error?: (m: string) => void };
+type RuntimeConnectionStore = Pick<
+  ClawChatStore,
+  "startConnection" | "markConnectSent" | "markConnectionReady" | "finishConnection"
+> &
+  Partial<
+    Pick<
+      ClawChatStore,
+      | "insertMessage"
+      | "claimMessageOnce"
+      | "updateMessageByIdentity"
+      | "claimPendingActivationBootstrap"
+      | "releaseActivationBootstrapClaim"
+      | "markActivationBootstrapSent"
+      | "upsertConversationSummary"
+      | "upsertConversationDetails"
+      | "deleteConversationCache"
+      | "listCachedConversationIds"
+      | "getActivationConversation"
+      | "getCachedConversation"
+    >
+  >;
 
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } =
   createPluginRuntimeStore<PluginRuntime>("openclaw-clawchat runtime not initialized");
@@ -34,11 +81,67 @@ const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingR
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 
 const activeClients = new Map<string, ClawlingChatClient>();
+const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate"]);
+const CLAWCHAT_MEMORY_ROOT_UNAVAILABLE =
+  "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved";
+const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
+  "approve",
+  "deny",
+  "always",
+  "cancel",
+  "yes",
+  "no",
+  "ok",
+  "confirm",
+  "remember",
+  "nevermind",
+]);
+
+function parseSlashCommandName(rawBody: string): string | null {
+  const stripped = rawBody.trimStart();
+  if (!stripped.startsWith("/")) return null;
+  const token = stripped.split(/\s+/, 1)[0] ?? "";
+  const name = token.slice(1).replace(/_/g, "-").toLowerCase();
+  if (!name || name.includes("/")) return null;
+  return name;
+}
+
+function isKnownOpenClawGroupSlashCommand(rawBody: string, cfg: OpenClawConfig): boolean {
+  const name = parseSlashCommandName(rawBody);
+  if (!name) return false;
+  return hasControlCommand(rawBody, cfg)
+    || CLAWCHAT_PLUGIN_SLASH_COMMANDS.has(name)
+    || OPENCLAW_CONFIRM_SLASH_COMMANDS.has(name);
+}
 
 export function getOpenclawClawlingClient(accountId: string): ClawlingChatClient | undefined {
   return activeClients.get(accountId);
 }
 
+export function resolveClawChatMemoryRoot(
+  runtime: PluginRuntime,
+  cfg: OpenClawConfig,
+  agentId: string,
+): string {
+  const resolver = runtime.agent?.resolveAgentWorkspaceDir;
+  if (typeof resolver !== "function") {
+    throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+  }
+
+  let workspaceDir: string;
+  try {
+    workspaceDir = resolver(cfg, agentId);
+  } catch {
+    throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+  }
+
+  const memoryRoot = typeof workspaceDir === "string" ? workspaceDir.trim() : "";
+  if (!memoryRoot) {
+    throw new Error(CLAWCHAT_MEMORY_ROOT_UNAVAILABLE);
+  }
+  return memoryRoot;
+}
+
 export async function waitForOpenclawClawlingClient(
   accountId: string,
   options: { timeoutMs?: number; pollMs?: number } = {},
@@ -112,6 +215,84 @@ function formatConversationSubject(peer: { kind: "direct" | "group"; id: string
   return peer.kind === "group" ? `group:${peer.id}` : peer.id;
 }
 
+function parseApiTimestamp(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" ? value as Record<string, unknown> : null;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function optionalNullableString(record: Record<string, unknown>, key: string): string | null | undefined {
+  if (!hasOwn(record, key)) return undefined;
+  const value = record[key];
+  if (value === null) return null;
+  return optionalString(value);
+}
+
+function isConversationNotFoundError(err: unknown): boolean {
+  if (!(err instanceof ClawlingApiError)) return false;
+  return err.meta?.status === 404 || err.meta?.status === 410 ||
+    err.meta?.code === 404 || err.meta?.code === 410 || err.meta?.code === 40401;
+}
+
+function metadataVersionFromEnvelope(env: Envelope): number | undefined {
+  const payload = asRecord(env.payload);
+  const version = payload?.version;
+  return typeof version === "number" && Number.isFinite(version) ? version : undefined;
+}
+
+function metadataScopesFromEnvelope(env: Envelope): string[] {
+  const scope = asRecord(env.payload)?.scope;
+  return Array.isArray(scope) ? scope.filter((item): item is string => typeof item === "string") : [];
+}
+
+function shouldRefreshBehaviorForScopes(scopes: string[]): boolean {
+  return scopes.includes("behavior");
+}
+
+function shouldRefreshConversationForScopes(scopes: string[]): boolean {
+  if (scopes.length === 0) return true;
+  return scopes.some((scope) => scope === "title" || scope === "description" || scope !== "behavior");
+}
+
+function buildConversationDetailsCacheInput(params: {
+  accountId: string;
+  conversation: ConversationDetails;
+  metadataVersion?: number;
+}): Parameters<NonNullable<RuntimeConnectionStore["upsertConversationDetails"]>>[0] {
+  const { accountId, conversation, metadataVersion } = params;
+  const refreshedAt = Date.now();
+  const participants = Array.isArray(conversation.participants) ? conversation.participants : [];
+  return {
+    platform: "openclaw",
+    accountId,
+    conversationId: conversation.id,
+    conversationType: conversation.type,
+    ...(metadataVersion !== undefined ? { metadataVersion } : {}),
+    lastSeenAt: parseApiTimestamp(conversation.updated_at),
+    lastRefreshedAt: refreshedAt,
+    raw: conversation,
+    members: participants.map((participant) => ({
+      userId: participant.user_id,
+      role: participant.role,
+      raw: participant,
+      lastSeenAt: parseApiTimestamp(participant.joined_at),
+    })),
+    membersComplete: true,
+  };
+}
+
 function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
   return {
     ...cfg,
@@ -122,6 +303,53 @@ function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
   };
 }
 
+function buildActivationBootstrapText(): string {
+  return [
+    "ClawChat activation bootstrap: You are now connected to this ClawChat direct conversation.",
+    "Please do both:",
+    "1. Send a brief, friendly greeting to the user in this ClawChat direct conversation.",
+    "2. If you have local profile information for yourself, such as display name, bio, or avatar, update the connected ClawChat account profile using the available ClawChat tools. Use `clawchat_update_account_profile` for display name/bio/avatar URL, and use `clawchat_upload_avatar_image` first if the avatar is only available as a local image path. If you do not have local profile information, skip profile updates and only greet the user.",
+    "Do not ask the user for profile information just for this bootstrap.",
+  ].join("\n");
+}
+
+function buildActivationBootstrapEnvelope(params: {
+  account: ResolvedOpenclawClawlingAccount;
+  conversationId: string;
+}): Envelope {
+  const text = buildActivationBootstrapText();
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `openclaw-clawchat-bootstrap-${now}`,
+    emitted_at: now,
+    chat_id: params.conversationId,
+    chat_type: "direct",
+    to: { id: params.account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-bootstrap",
+      type: "direct",
+      nick_name: "ClawChat Activation",
+    },
+    payload: {
+      message_id: `openclaw-clawchat-bootstrap-${params.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,
+        },
+      },
+    },
+  };
+}
+
 export interface StartGatewayParams {
   cfg: OpenClawConfig;
   account: ResolvedOpenclawClawlingAccount;
@@ -130,25 +358,59 @@ export interface StartGatewayParams {
   getStatus: () => ChannelAccountSnapshot;
   log?: Log;
   /** Test hook only. */
+  store?: RuntimeConnectionStore | null;
+  /** Test hook only. */
   transport?: Transport;
 }
 
+function resolveConnectionStore(
+  params: StartGatewayParams,
+  runtime: PluginRuntime,
+): RuntimeConnectionStore | null {
+  if (params.store !== undefined) return params.store;
+  if (params.transport) return null;
+  try {
+    const stateDir = runtime.state?.resolveStateDir?.();
+    return getClawChatStore({
+      ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+      log: { error: (message) => params.log?.error?.(message) },
+    });
+  } catch {
+    params.log?.error?.("openclaw-clawchat sqlite connection persistence unavailable; continuing.");
+    return null;
+  }
+}
+
 export async function startOpenclawClawlingGateway(params: StartGatewayParams): Promise<void> {
   const { cfg, account, abortSignal, setStatus, getStatus, log } = params;
   // Obtain PluginRuntime from the stored runtime set via setOpenclawClawlingRuntime.
   const runtime = getOpenclawClawlingRuntime();
   const accountId = account.accountId;
+  const store = resolveConnectionStore(params, runtime);
+  let conversationApiClient: ReturnType<typeof createOpenclawClawlingApiClient> | undefined;
+  const getConversationApiClient = () => {
+    conversationApiClient ??= createOpenclawClawlingApiClient({
+      baseUrl: account.baseUrl,
+      token: account.token,
+      userId: account.userId,
+    });
+    return conversationApiClient;
+  };
 
   log?.info?.(
-    `[${accountId}] openclaw-clawchat runtime start entered configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} websocketUrl=${account.websocketUrl || "(empty)"}`,
+    `[${accountId}] openclaw-clawchat runtime start entered configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} hasOwnerUserId=${Boolean(account.ownerUserId)} websocketUrl=${account.websocketUrl || "(empty)"}`,
   );
   let lastHelloFailTraceId = "-";
   let lastHelloFailReason = "";
   let lastConnectTraceId = "-";
+  let lastHelloOkDeviceId: string | undefined;
+  let lastHelloOkDeliveryMode: string | undefined;
   let currentAttemptStartedAt = 0;
   let authFailureLogged = false;
   let closingForAbort = false;
   let wsReady = false;
+  let currentConnectionId: number | null = null;
+  let currentConnectionFinished = false;
   const reconnectTracker = createReconnectTracker({
     accountId,
     log: (msg) => log?.info?.(msg),
@@ -162,11 +424,243 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       state: snapshot.state === "connected" ? "ready" : snapshot.state,
     };
   };
+  const recordConnection = <T>(action: string, fn: () => T): T | undefined => {
+    try {
+      return fn();
+    } catch {
+      log?.error?.(`[${accountId}] openclaw-clawchat sqlite ${action} failed; continuing`);
+      return undefined;
+    }
+  };
+  const finishCurrentConnection = (input: {
+    state: string;
+    disconnectedAt?: number;
+    closeCode?: number | null;
+    closeReason?: string | null;
+    error?: string | null;
+  }) => {
+    if (!store || currentConnectionId == null || currentConnectionFinished) return;
+    const connectionId = currentConnectionId;
+    recordConnection("finish", () => store.finishConnection(connectionId, input));
+    currentConnectionFinished = true;
+    currentConnectionId = null;
+  };
+  const refreshConversationDetails = async (
+    conversationId: string,
+    options: { metadataVersion?: number; source: string; memoryRoot?: string },
+  ): Promise<void> => {
+    try {
+      const memoryRoot = options.memoryRoot;
+      const data = memoryRoot
+        ? await (async () => {
+            const result = await pullGroupMetadata({
+              memoryRoot,
+              groupId: conversationId,
+              api: getConversationApiClient(),
+            });
+            if (result.failures.length > 0) {
+              log?.error?.(
+                `[${accountId}] openclaw-clawchat group participant metadata refresh partially failed: ${result.failures.map((failure) => `${failure.targetId}: ${failure.error}`).join("; ")}`,
+              );
+            }
+            if (!result.conversation) throw new Error("ClawChat conversation metadata response is missing conversation");
+            return { conversation: result.conversation };
+          })()
+        : await getConversationApiClient().getConversation(conversationId);
+      if (!store?.upsertConversationDetails) return;
+      recordConnection("conversation details upsert", () =>
+        store.upsertConversationDetails?.(buildConversationDetailsCacheInput({
+          accountId,
+          conversation: data.conversation,
+          ...(options.metadataVersion !== undefined ? { metadataVersion: options.metadataVersion } : {}),
+        })),
+      );
+    } catch (err) {
+      if (isConversationNotFoundError(err)) {
+        if (store?.deleteConversationCache) {
+          recordConnection("conversation cache delete", () =>
+            store.deleteConversationCache?.({
+              platform: "openclaw",
+              accountId,
+              conversationId,
+            }),
+          );
+        }
+        return;
+      }
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat metadata refresh failed source=${options.source} conversation=${conversationId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  const refreshAgentBehavior = async (options: {
+    metadataVersion?: number;
+    source: string;
+    memoryRoot: string;
+  }): Promise<void> => {
+    try {
+      await pullOwnerMetadata({
+        memoryRoot: options.memoryRoot,
+        agentId: account.agentId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        api: getConversationApiClient(),
+      });
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat behavior refresh failed source=${options.source} agent=${account.userId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  const refreshConversationCacheAfterReady = async (): Promise<void> => {
+    if (!store) return;
+    const ids: string[] = [];
+    const seen = new Set<string>();
+    const addId = (id: unknown) => {
+      if (typeof id !== "string" || !id || seen.has(id)) return;
+      seen.add(id);
+      ids.push(id);
+    };
+
+    const activation = store.getActivationConversation
+      ? recordConnection("activation conversation read", () =>
+          store.getActivationConversation?.({ platform: "openclaw", accountId }),
+        )
+      : null;
+    addId(activation?.conversationId);
+
+    const cachedIds = store.listCachedConversationIds
+      ? recordConnection("cached conversation ids read", () =>
+          store.listCachedConversationIds?.({ platform: "openclaw", accountId, limit: 20 }),
+        ) ?? []
+      : [];
+    for (const id of cachedIds.slice(0, 20)) addId(id);
+
+    for (const id of ids) {
+      await refreshConversationDetails(id, { source: "reconnect" });
+    }
+  };
+  const resolveMemoryRootForPeer = (peer: { kind: "direct" | "group"; id: string }): string | null => {
+    try {
+      const route = runtime.channel.routing.resolveAgentRoute({
+        cfg: withClawChatSessionScope(cfg),
+        channel: CHANNEL_ID,
+        accountId,
+        peer,
+      });
+      return resolveClawChatMemoryRoot(runtime, cfg, route.agentId);
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat metadata refresh memory root unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return null;
+    }
+  };
+  const handleMetadataInvalidation = async (env: Envelope): Promise<void> => {
+    const conversationId = typeof env.chat_id === "string" && env.chat_id.trim()
+      ? env.chat_id
+      : "";
+    if (!conversationId) {
+      log?.info?.(`[${accountId}] openclaw-clawchat metadata invalidation missing chat_id trace=${env.trace_id}`);
+      return;
+    }
+
+    const version = metadataVersionFromEnvelope(env);
+    const scopes = metadataScopesFromEnvelope(env);
+    const refreshBehavior = shouldRefreshBehaviorForScopes(scopes);
+    const refreshConversation = shouldRefreshConversationForScopes(scopes);
+    if (!refreshBehavior && !refreshConversation) return;
+    const peer = {
+      kind: env.chat_type === "group" ? "group" as const : "direct" as const,
+      id: conversationId,
+    };
+    const memoryRoot = resolveMemoryRootForPeer(peer);
+    if (!memoryRoot) return;
+
+    if (refreshBehavior) {
+      await refreshAgentBehavior({
+        source: "metadata_invalidation",
+        ...(version !== undefined ? { metadataVersion: version } : {}),
+        memoryRoot,
+      });
+    }
+
+    if (!refreshConversation) return;
+
+    await refreshConversationDetails(conversationId, {
+      source: "metadata_invalidation",
+      ...(version !== undefined ? { metadataVersion: version } : {}),
+      memoryRoot,
+    });
+  };
+  const syncMessagePathProfiles = async (turn: IngestTurnParams, memoryRoot: string): Promise<void> => {
+    if (turn.senderId === "clawchat-bootstrap") {
+      await pullOwnerMetadata({
+        memoryRoot,
+        agentId: account.agentId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        api: getConversationApiClient(),
+      });
+      return;
+    }
+    if (turn.peer.kind === "direct" && (turn.senderId === account.ownerUserId || turn.senderId === account.userId)) {
+      await pullOwnerMetadata({
+        memoryRoot,
+        agentId: account.agentId,
+        accountUserId: account.userId,
+        accountOwnerUserId: account.ownerUserId,
+        api: getConversationApiClient(),
+      });
+      return;
+    }
+    if (turn.peer.kind === "group") {
+      await refreshGroupProfile({
+        platform: "openclaw",
+        accountId,
+        conversationId: turn.peer.id,
+        api: getConversationApiClient(),
+        store: {
+          ...(store?.upsertConversationDetails ? { upsertConversationDetails: store.upsertConversationDetails.bind(store) } : {}),
+        },
+        memoryRoot,
+        log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+      });
+      return;
+    }
+    await syncFirstSeenClawChatProfiles({
+      platform: "openclaw",
+      accountId,
+      accountUserId: account.userId,
+      accountOwnerUserId: account.ownerUserId,
+      chat: {
+        id: turn.peer.id,
+        type: "direct",
+        lastSeenAt: turn.timestamp,
+      },
+      sender: {
+        id: turn.senderId,
+        ...(turn.senderNickName ? { nickname: turn.senderNickName } : {}),
+      },
+      api: getConversationApiClient(),
+      store: {
+        ...(store?.getCachedConversation ? { getCachedConversation: store.getCachedConversation.bind(store) } : {}),
+        ...(store?.upsertConversationSummary ? { upsertConversationSummary: store.upsertConversationSummary.bind(store) } : {}),
+        ...(store?.upsertConversationDetails ? { upsertConversationDetails: store.upsertConversationDetails.bind(store) } : {}),
+      },
+      memoryRoot,
+      log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+    });
+  };
   const client = createOpenclawClawlingClient(account, {
     ...(params.transport ? { transport: params.transport } : {}),
     wsLifecycle: {
       onConnectFrameSent: (env) => {
         lastConnectTraceId = typeof env.trace_id === "string" ? env.trace_id : "-";
+        if (store && currentConnectionId != null) {
+          const connectionId = currentConnectionId;
+          recordConnection("connect-sent", () => store.markConnectSent(connectionId));
+        }
         const deviceId =
           typeof env.payload?.device_id === "string" ? env.payload.device_id : "-";
         const current = wsLogContext();
@@ -190,6 +684,13 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   log?.info?.(`[${accountId}] openclaw-clawchat runtime client created`);
 
   setAlignedOutboundLogContext(client, wsLogContext);
+  client.on("hello:ok", (env: Envelope) => {
+    const payload = env.payload && typeof env.payload === "object"
+      ? env.payload as { device_id?: unknown; delivery_mode?: unknown }
+      : {};
+    lastHelloOkDeviceId = typeof payload.device_id === "string" ? payload.device_id : undefined;
+    lastHelloOkDeliveryMode = typeof payload.delivery_mode === "string" ? payload.delivery_mode : undefined;
+  });
   const protocolControlLogger = createProtocolControlHandler({
     accountId,
     log: (msg) => log?.info?.(msg),
@@ -215,6 +716,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }),
     );
   };
+  let dispatchActivationBootstrap: () => Promise<void> = async () => {};
 
   client.on("state", ({ from, to }) => {
     log?.info?.(`[${accountId}] openclaw-clawchat state ${from} -> ${to}`);
@@ -223,6 +725,18 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       reconnectTracker.connectStart();
       currentAttemptStartedAt = Date.now();
       const current = wsLogContext();
+      if (store) {
+        recordConnection("start", () => {
+          currentConnectionId = store.startConnection({
+            platform: "openclaw",
+            accountId,
+            attempt: current.attempt,
+            reconnectCount: current.reconnectCount,
+            connectStartedAt: currentAttemptStartedAt,
+          });
+          currentConnectionFinished = false;
+        });
+      }
       log?.info?.(
         formatWsLog({
           event: "connect_start",
@@ -242,6 +756,19 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       const queueSize = getAlignedOutboundQueueSize(client);
       reconnectTracker.markReady();
       const current = wsLogContext();
+      if (store && currentConnectionId != null) {
+        const connectionId = currentConnectionId;
+        recordConnection("ready", () => {
+          if (lastHelloOkDeviceId === undefined && lastHelloOkDeliveryMode === undefined) {
+            store.markConnectionReady(connectionId);
+            return;
+          }
+          store.markConnectionReady(connectionId, {
+            ...(lastHelloOkDeviceId !== undefined ? { resolvedDeviceId: lastHelloOkDeviceId } : {}),
+            ...(lastHelloOkDeliveryMode !== undefined ? { deliveryMode: lastHelloOkDeliveryMode } : {}),
+          });
+        });
+      }
       log?.info?.(
         formatWsLog({
           event: "handshake_ok",
@@ -262,6 +789,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       } catch {
         // The queue keeps the failed frame at the head and will retry after the next reconnect.
       }
+      void refreshConversationCacheAfterReady();
+      void dispatchActivationBootstrap();
     } else if (to === "disconnected") {
       reconnectTracker.markClosed();
     }
@@ -271,6 +800,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
 
   client.on("close", ({ code, reason }: { code?: number; reason?: string }) => {
     if (closingForAbort || (code === 1000 && reason === "client close")) return;
+    finishCurrentConnection({
+      state: "disconnected",
+      closeCode: code ?? null,
+      closeReason: reason ?? null,
+    });
     const current = wsLogContext();
     log?.info?.(
       formatWsLog({
@@ -398,9 +932,17 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     lastHelloFailReason = typeof payload?.reason === "string" ? payload.reason : "";
   });
 
+  client.on("metadata:invalidated", (env: Envelope) => {
+    void handleMetadataInvalidation(env);
+  });
+
   client.on("error", (err: unknown) => {
     const classified = classifyClawlingClientError(err);
     if (classified.kind === "auth") {
+      finishCurrentConnection({
+        state: "auth_failed",
+        error: lastHelloFailReason || classified.message,
+      });
       logAuthFailure(classified.message);
       setStatus({
         ...getStatus(),
@@ -410,6 +952,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         lastError: classified.message,
       });
     } else if (classified.kind === "transport") {
+      finishCurrentConnection({ state: "transport_error", error: classified.message });
       const current = wsLogContext();
       log?.info?.(
         formatWsLog({
@@ -436,153 +979,428 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     } else if (classified.kind === "state") {
       log?.info?.(`[${accountId}] openclaw-clawchat state error: ${classified.message}`);
     } else {
-      log?.error?.(`[${accountId}] openclaw-clawchat sdk error: ${classified.message}`);
+      log?.error?.(`[${accountId}] openclaw-clawchat client error: ${classified.message}`);
     }
   });
 
-  client.on("message", async (env: Envelope) => {
+  type IngestTurnResult = "submitted" | "skipped" | "failed";
+  type GroupIngestTurnParams = IngestTurnParams & { peer: { kind: "group"; id: string } };
+
+  const buildPromptForTurn = async (turn: IngestTurnParams, memoryRoot: string): Promise<string> => {
+    const senderRelation = resolveSenderRelation({
+      senderId: turn.senderId,
+      accountUserId: account.userId,
+      accountOwnerUserId: account.ownerUserId,
+      senderProfileType: turn.senderProfileType,
+    });
+    const promptChatType = turn.peer.kind === "group" ? "group" : "dm";
+    const promptMetadata = await loadClawChatPromptMetadata({
+      memoryRoot,
+      turn: {
+        chatType: promptChatType,
+        senderId: turn.senderId,
+        senderIsOwner: senderRelation === "owner",
+        groupId: turn.peer.kind === "group" ? turn.peer.id : null,
+      },
+      log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+    });
+    const metadataSenderProfileType = promptMetadata.userMetadata?.profile_type ?? null;
+    const promptSenderProfileType = metadataSenderProfileType ?? turn.senderProfileType ?? (
+      senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"
+    );
+    return renderClawChatProfilePrompt({
+      basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
+      ...promptMetadata,
+      turn: {
+        chatType: promptChatType,
+        senderId: turn.senderId,
+        senderName: promptMetadata.userMetadata?.nickname ?? (turn.senderNickName || turn.senderId),
+        senderProfileType: promptSenderProfileType,
+        senderIsOwner: senderRelation === "owner",
+        groupId: turn.peer.kind === "group" ? turn.peer.id : null,
+        coalescedGroupBatch: turn.coalescedGroupBatch === true,
+        wasMentioned: turn.wasMentioned,
+        mentionedUserIds: turn.mentionedUserIds,
+      },
+    });
+  };
+
+  const resolveSenderNickNameForTurn = (turn: IngestTurnParams): string => {
+    if (turn.senderNickName && turn.senderNickName !== turn.senderId) return turn.senderNickName;
+    return turn.senderNickName || turn.senderId;
+  };
+
+  const resolveSenderBatchIdentityForTurn = (turn: IngestTurnParams): {
+    senderRelation: NonNullable<IngestTurnParams["senderRelation"]>;
+    senderProfileType: string;
+    senderIsOwner: boolean;
+  } => {
+    const senderRelation = resolveSenderRelation({
+      senderId: turn.senderId,
+      accountUserId: account.userId,
+      accountOwnerUserId: account.ownerUserId,
+      senderProfileType: turn.senderProfileType,
+    });
+    return {
+      senderRelation,
+      senderProfileType: turn.senderProfileType ??
+        (senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"),
+      senderIsOwner: senderRelation === "owner",
+    };
+  };
+
+  const claimInboundTurn = (turn: IngestTurnParams): "claimed" | "skipped" => {
+    const env = turn.envelope;
+    if (store?.claimMessageOnce) {
+      const claimed = recordConnection("message claim", () =>
+        store.claimMessageOnce?.({
+          platform: "openclaw",
+          accountId,
+          kind: "message",
+          direction: "inbound",
+          eventType: String(env.event),
+          traceId: turn.traceId,
+          chatId: turn.peer.id,
+          messageId: turn.messageId,
+          text: turn.rawBody,
+          raw: env,
+        }),
+      );
+      if (claimed === false) {
+        log?.info?.(
+          `[${accountId}] openclaw-clawchat skip duplicate stored msg=${turn.messageId}`,
+        );
+        return "skipped";
+      }
+    }
+    return "claimed";
+  };
+
+  const dispatchTurnToAgent = async (turn: IngestTurnParams): Promise<IngestTurnResult> => {
+    const rt = runtime.channel;
+    const storePath = rt.session.resolveStorePath(cfg.session?.store);
+    const routeCfg = withClawChatSessionScope(cfg);
+    const route = rt.routing.resolveAgentRoute({
+      cfg: routeCfg,
+      channel: CHANNEL_ID,
+      accountId,
+      peer: turn.peer,
+    });
+    const memoryRoot = resolveClawChatMemoryRoot(runtime, cfg, route.agentId);
+    const body = rt.reply.formatAgentEnvelope({
+      channel: "Clawling Chat",
+      from: formatConversationSubject(turn.peer),
+      body: turn.rawBody,
+      timestamp: turn.timestamp,
+      ...rt.reply.resolveEnvelopeFormatOptions(cfg),
+    });
     try {
-      await dispatchOpenclawClawlingInbound({
-        envelope: env as Envelope<unknown>,
-        cfg,
-        runtime,
-        account,
-        log,
-        ingest: async (turn) => {
-          const rt = runtime.channel;
-          const storePath = rt.session.resolveStorePath(cfg.session?.store);
-          const routeCfg = withClawChatSessionScope(cfg);
-          const route = rt.routing.resolveAgentRoute({
-            cfg: routeCfg,
-            channel: CHANNEL_ID,
-            accountId,
-            peer: turn.peer,
-          });
-          const body = rt.reply.formatAgentEnvelope({
-            channel: "Clawling Chat",
-            from: formatConversationSubject(turn.peer),
-            body: turn.rawBody,
-            timestamp: turn.timestamp,
-            ...rt.reply.resolveEnvelopeFormatOptions(cfg),
-          });
-          const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
-          const ctxPayload = rt.reply.finalizeInboundContext({
-            Body: body,
-            BodyForAgent: turn.rawBody,
-            RawBody: turn.rawBody,
-            CommandBody: turn.rawBody,
-            // Clawling v2 routes by chat_id. `OriginatingTo` is what the
-            // message tool uses as the implicit current-chat target, so keep it
-            // on the conversation id rather than the agent account user id.
-            From: conversationTarget,
-            To: `${CHANNEL_ID}:${account.userId}`,
-            SessionKey: route.sessionKey,
-            AccountId: route.accountId ?? accountId,
-            ChatType: turn.peer.kind,
-            ConversationLabel: formatConversationSubject(turn.peer),
-            SenderId: turn.senderId,
-            Provider: CHANNEL_ID,
-            Surface: CHANNEL_ID,
-            MessageSid: turn.messageId,
-            MessageSidFull: turn.messageId,
-            Timestamp: turn.timestamp,
-            OriginatingChannel: CHANNEL_ID,
-            OriginatingTo: conversationTarget,
-          });
-          // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
-          const inboundPaths =
-            turn.mediaItems.length > 0
-              ? await fetchInboundMedia(turn.mediaItems, {
-                  runtime,
-                  log,
-                  maxBytes: 20 * 1024 * 1024,
-                })
-              : [];
-          if (inboundPaths.length > 0) {
-            (ctxPayload as Record<string, unknown>).MediaPath = inboundPaths[0];
-            (ctxPayload as Record<string, unknown>).MediaPaths = inboundPaths;
-          }
+      await syncMessagePathProfiles(turn, memoryRoot);
+    } catch (err) {
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat message metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
+    const turnPrompt = await buildPromptForTurn(turn, memoryRoot);
+    const ctxPayload = rt.turn.buildContext({
+      channel: CHANNEL_ID,
+      accountId: route.accountId ?? accountId,
+      provider: CHANNEL_ID,
+      surface: CHANNEL_ID,
+      messageId: turn.messageId,
+      messageIdFull: turn.messageId,
+      timestamp: turn.timestamp,
+      from: conversationTarget,
+      sender: {
+        id: turn.senderId,
+        name: turn.senderNickName || turn.senderId,
+        displayLabel: turn.senderNickName || turn.senderId,
+      },
+      conversation: {
+        kind: turn.peer.kind,
+        id: turn.peer.id,
+        label: formatConversationSubject(turn.peer),
+        routePeer: turn.peer,
+      },
+      route: {
+        agentId: route.agentId,
+        accountId: route.accountId ?? accountId,
+        routeSessionKey: route.sessionKey,
+      },
+      reply: {
+        to: `${CHANNEL_ID}:${account.userId}`,
+        originatingTo: conversationTarget,
+      },
+      message: {
+        body,
+        rawBody: turn.rawBody,
+        bodyForAgent: turn.rawBody,
+        commandBody: turn.rawBody,
+        envelopeFrom: conversationTarget,
+      },
+      access: {
+        mentions: {
+          canDetectMention: true,
+          wasMentioned: turn.wasMentioned,
+          hasAnyMention: turn.mentionedUserIds.length > 0,
+        },
+      },
+      ...(memoryRoot ? { extra: { memoryRoot } } : {}),
+      ...(turn.peer.kind === "group"
+        ? { supplemental: { groupSystemPrompt: turnPrompt } }
+        : {}),
+    });
+    if (memoryRoot) {
+      (ctxPayload as Record<string, unknown>).memoryRoot = memoryRoot;
+    }
+    if (turn.mentionedUserIds.length > 0) {
+      (ctxPayload as Record<string, unknown>).MentionedUserIds = turn.mentionedUserIds;
+    }
+    // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
+    const inboundPaths =
+      turn.mediaItems.length > 0
+        ? await fetchInboundMedia(turn.mediaItems, {
+            runtime,
+            log,
+            maxBytes: 20 * 1024 * 1024,
+          })
+        : [];
+    if (inboundPaths.length > 0) {
+      (ctxPayload as Record<string, unknown>).MediaPath = inboundPaths[0];
+      (ctxPayload as Record<string, unknown>).MediaPaths = inboundPaths;
+    }
 
-          try {
-            await rt.session.recordInboundSession({
-              storePath,
-              sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-              ctx: ctxPayload,
-              onRecordError: (err) => {
-                log?.error?.(
-                  `[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`,
-                );
-              },
-            });
-          } catch (err) {
+    const resolvedSessionKey = ctxPayload.SessionKey ?? route.sessionKey;
+
+    clearClawChatPromptInjectionForSession(resolvedSessionKey);
+    const stagedDirectPrompt = turn.peer.kind !== "group";
+    if (stagedDirectPrompt) {
+      stageClawChatPromptInjection({
+        sessionKey: resolvedSessionKey,
+        prompt: turnPrompt,
+      });
+    }
+
+    try {
+      try {
+        await rt.session.recordInboundSession({
+          storePath,
+          sessionKey: resolvedSessionKey,
+          ctx: ctxPayload,
+          onRecordError: (err) => {
             log?.error?.(
               `[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`,
             );
-          }
+          },
+        });
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`,
+        );
+      }
 
-          const replyCtx = turn.replyCtx;
-          const { dispatcher, replyOptions, markDispatchIdle } =
-            createOpenclawClawlingReplyDispatcher({
-              cfg,
-              runtime,
-              account,
-              client,
-              target: { chatId: turn.peer.id, chatType: turn.peer.kind },
-              ...(replyCtx ? { replyCtx } : {}),
-              inboundMessageId: turn.messageId,
-              inboundForFinalReply: {
-                chatId: turn.peer.id,
-                senderId: turn.senderId,
-                senderNickName: turn.senderNickName || turn.senderId,
-                bodyText: turn.rawBody,
-              },
-              log,
-            });
+      const replyCtx = turn.replyCtx;
+      const { dispatcher, replyOptions, markDispatchIdle } =
+        createOpenclawClawlingReplyDispatcher({
+          cfg,
+          runtime,
+          account,
+          client,
+          target: { chatId: turn.peer.id, chatType: turn.peer.kind },
+          ...(replyCtx ? { replyCtx } : {}),
+          inboundMessageId: turn.messageId,
+          inboundForFinalReply: {
+            chatId: turn.peer.id,
+            senderId: turn.senderId,
+            senderNickName: turn.senderNickName || turn.senderId,
+            bodyText: turn.rawBody,
+          },
+          store: store
+            ? {
+                insertMessage: (input) => store.insertMessage?.(input) ?? null,
+                claimMessageOnce: (input) => store.claimMessageOnce?.(input) ?? null,
+                updateMessageByIdentity: (input) => store.updateMessageByIdentity?.(input),
+              }
+            : null,
+          log,
+        });
 
-          const agentsConfigured = Object.keys((cfg as { agents?: Record<string, unknown> }).agents ?? {});
+      const agentsConfigured = Object.keys((cfg as { agents?: Record<string, unknown> }).agents ?? {});
+      log?.info?.(
+        `[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${resolvedSessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
+      );
+
+      try {
+        const dispatchResult = await rt.reply.withReplyDispatcher({
+          dispatcher,
+          onSettled: () => markDispatchIdle(),
+          run: () => rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
+        });
+        const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
+        const queuedFinal = Boolean(
+          (dispatchResult as { queuedFinal?: boolean } | undefined)?.queuedFinal,
+        );
+        log?.info?.(
+          `[${accountId}] openclaw-clawchat dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`,
+        );
+        if (!queuedFinal && Object.values(counts).every((n) => !n)) {
           log?.info?.(
-            `[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${ctxPayload.SessionKey ?? route.sessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
+            `[${accountId}] openclaw-clawchat NO reply was produced (no final / block / tool dispatched). ` +
+              `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
+              `or send-policy denied; or a plugin claimed the binding.`,
           );
+        }
+        return "submitted";
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
+        );
+        return "failed";
+      }
+    } finally {
+      if (stagedDirectPrompt) {
+        clearClawChatPromptInjectionForSession(resolvedSessionKey);
+      }
+    }
+  };
 
-          try {
-            const dispatchResult = await rt.reply.withReplyDispatcher({
-              dispatcher,
-              onSettled: () => markDispatchIdle(),
-              run: () =>
-                rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
-            });
-            const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
-            const queuedFinal = Boolean(
-              (dispatchResult as { queuedFinal?: boolean } | undefined)?.queuedFinal,
-            );
-            log?.info?.(
-              `[${accountId}] openclaw-clawchat dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`,
-            );
-            if (!queuedFinal && Object.values(counts).every((n) => !n)) {
-              log?.info?.(
-                `[${accountId}] openclaw-clawchat NO reply was produced (no final / block / tool dispatched). ` +
-                  `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
-                  `or send-policy denied; or a plugin claimed the binding.`,
-              );
-            }
-          } catch (err) {
-            log?.error?.(
-              `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
-            );
-          }
+  const groupCoalescer = createGroupMessageCoalescer<GroupIngestTurnParams>({
+    idleMs: 10_000,
+    maxWaitMs: 30_000,
+    dispatch: async (turn) => {
+      await dispatchTurnToAgent(turn);
+    },
+    onError: (err) => {
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat coalesced group dispatch failed: ${String(err)}`,
+      );
+    },
+    onDrop: (chatId, count) => {
+      log?.info?.(
+        `[${accountId}] openclaw-clawchat dropped pending group batch chat_id=${chatId} count=${count} reason=shutdown`,
+      );
+    },
+  });
+
+  const ingestTurn = async (rawTurn: IngestTurnParams): Promise<IngestTurnResult> => {
+    const senderBatchIdentity = rawTurn.peer.kind === "group"
+      ? resolveSenderBatchIdentityForTurn(rawTurn)
+      : {};
+    const turn: IngestTurnParams = {
+      ...rawTurn,
+      senderNickName: resolveSenderNickNameForTurn(rawTurn),
+      ...senderBatchIdentity,
+    };
+    const claimed = claimInboundTurn(turn);
+    if (claimed === "skipped") return "skipped";
+    if (turn.peer.kind === "group") {
+      if (isKnownOpenClawGroupSlashCommand(turn.rawBody, cfg)) {
+        const commandMode = effectiveGroupCommandMode(account, turn.peer.id);
+        const commandAllowed = commandMode === "all"
+          || (commandMode === "owner" && turn.senderIsOwner === true);
+        if (!commandAllowed) {
+          log?.info?.(
+            `[${accountId}] openclaw-clawchat group command dropped chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode} owner=${turn.senderIsOwner === true}`,
+          );
+          return "skipped";
+        }
+        log?.info?.(
+          `[${accountId}] openclaw-clawchat dispatching group command chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode}`,
+        );
+        return dispatchTurnToAgent(turn);
+      }
+      if (turn.wasMentioned) {
+        groupCoalescer.enqueue(turn as GroupIngestTurnParams);
+        groupCoalescer.flushNow(turn.peer.id);
+        log?.info?.(
+          `[${accountId}] openclaw-clawchat dispatching mentioned group batch chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        );
+        return "submitted";
+      }
+      groupCoalescer.enqueue(turn as GroupIngestTurnParams);
+      log?.info?.(
+        `[${accountId}] openclaw-clawchat queued group batch chat_id=${turn.peer.id} msg=${turn.messageId}`,
+      );
+      return "submitted";
+    }
+    return dispatchTurnToAgent(turn);
+  };
+
+  const handleInboundEnvelope = async (env: Envelope): Promise<IngestTurnResult | undefined> => {
+    let ingestResult: IngestTurnResult | undefined;
+    try {
+      await dispatchOpenclawClawlingInbound({
+        envelope: env as Envelope<unknown>,
+        cfg,
+        runtime,
+        account,
+        log,
+        ingest: async (turn) => {
+          ingestResult = await ingestTurn(turn);
         },
       });
     } catch (err) {
       log?.error?.(
         `[${accountId}] openclaw-clawchat message handler error: ${err instanceof Error ? err.stack || err.message : String(err)}`,
       );
+      return "failed";
+    }
+    return ingestResult;
+  };
+
+  dispatchActivationBootstrap = async (): Promise<void> => {
+    if (!store?.claimPendingActivationBootstrap || !store.markActivationBootstrapSent) return;
+    let bootstrap: { conversationId: string } | null | undefined;
+    const releaseBootstrap = () => {
+      if (!bootstrap || !store.releaseActivationBootstrapClaim) return;
+      const claimedBootstrap = bootstrap;
+      recordConnection("activation bootstrap release", () =>
+        store.releaseActivationBootstrapClaim?.({
+          platform: "openclaw",
+          accountId,
+          conversationId: claimedBootstrap.conversationId,
+        }),
+      );
+    };
+    try {
+      bootstrap = recordConnection("activation bootstrap claim", () =>
+        store.claimPendingActivationBootstrap?.({ platform: "openclaw", accountId }),
+      );
+      if (!bootstrap) return;
+      const claimedBootstrap = bootstrap;
+      const result = await handleInboundEnvelope(
+        buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }),
+      );
+      if (result !== "submitted") {
+        releaseBootstrap();
+        return;
+      }
+      recordConnection("activation bootstrap sent", () =>
+        store.markActivationBootstrapSent?.({
+          platform: "openclaw",
+          accountId,
+          conversationId: claimedBootstrap.conversationId,
+        }),
+      );
+    } catch (err) {
+      releaseBootstrap();
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat activation bootstrap failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
     }
+  };
+
+  client.on("message", (env: Envelope) => {
+    void (async () => {
+      await handleInboundEnvelope(env);
+    })();
   });
 
   // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
   // (auth). Transport failures (server unreachable, DNS error, etc.) do
-  // NOT reject this promise — the SDK catches them internally and drives
-  // its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
+  // NOT reject this promise — the local client handles them internally and
+  // drives its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
   // capped at `maxDelay`, with jitter). So we never throw here on anything
   // other than auth failure; on auth we tear the account down cleanly and
   // return without throwing (which would make the gateway supervisor
@@ -601,6 +1419,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       lastError: classified.message,
     });
     if (classified.kind === "auth") {
+      finishCurrentConnection({
+        state: "auth_failed",
+        error: lastHelloFailReason || classified.message,
+      });
       logAuthFailure(classified.message);
       return;
     }
@@ -623,6 +1445,12 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     log?.info?.(`[${accountId}] openclaw-clawchat runtime abort received; closing client`);
     activeClients.delete(accountId);
     closingForAbort = true;
+    groupCoalescer.cancelAll();
+    finishCurrentConnection({
+      state: "disconnected",
+      closeCode: 1000,
+      closeReason: "client close",
+    });
     client.close();
     setStatus({
       ...getStatus(),