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

package/src/runtime.test.ts

@@ -1,9 +1,14 @@
-import { MockTransport, AuthError } from "@newbase-clawchat/sdk";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockTransport } from "./mock-transport.ts";
+import { AuthError } from "./protocol-types.ts";
 import {
   classifyClawlingClientError,
   mapClawlingStateToStatus,
+  resolveClawChatMemoryRoot,
   setOpenclawClawlingRuntime,
   getOpenclawClawlingRuntime,
   startOpenclawClawlingGateway,
@@ -11,6 +16,13 @@ import {
 } from "./runtime.ts";
 import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 import { sendOpenclawClawlingText } from "./outbound.ts";
+import {
+  clearClawChatPromptInjections,
+  registerClawChatPromptInjection,
+  renderClawChatPromptInjectionForSession,
+  stageClawChatPromptInjection,
+} from "./prompt-injection.ts";
+import { readClawChatMemoryFile, writeClawChatMetadata } from "./clawchat-memory.ts";
 
 function baseAccount(
   overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
@@ -23,10 +35,16 @@ function baseAccount(
     websocketUrl: "ws://t",
     baseUrl: "https://api.example.com",
     token: "tk",
+    agentId: "agt-1",
     userId: "u",
+    ownerUserId: "owner-u",
     replyMode: "static",
+    groupMode: "all",
+    groupCommandMode: "owner",
+    groups: {},
     forwardThinking: true,
     forwardToolCalls: false,
+    richInteractions: false,
     allowFrom: [],
     stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
     reconnect: {
@@ -41,8 +59,729 @@ function baseAccount(
   };
 }
 
+const EXPECTED_ACTIVATION_BOOTSTRAP_TEXT = [
+  "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");
+
+beforeEach(() => {
+  clearClawChatPromptInjections();
+});
+
+function buildTestInboundContext(params: {
+  channel: string;
+  accountId?: string;
+  provider?: string;
+  surface?: string;
+  messageId?: string;
+  messageIdFull?: string;
+  timestamp?: number;
+  from: string;
+  sender: { id: string; name?: string; displayLabel?: string };
+  conversation: { kind: "direct" | "group" | "channel"; label?: string };
+  route: { accountId?: string; routeSessionKey: string; dispatchSessionKey?: string };
+  reply: { to: string; originatingTo: string };
+  message: { body?: string; rawBody: string; bodyForAgent?: string; commandBody?: string };
+  access?: { mentions?: { wasMentioned?: boolean; mentionedUserIds?: string[] } };
+  supplemental?: { groupSystemPrompt?: string };
+}) {
+  return {
+    Body: params.message.body ?? params.message.rawBody,
+    BodyForAgent: params.message.bodyForAgent ?? params.message.rawBody,
+    RawBody: params.message.rawBody,
+    CommandBody: params.message.commandBody ?? params.message.rawBody,
+    From: params.from,
+    To: params.reply.to,
+    SessionKey: params.route.dispatchSessionKey ?? params.route.routeSessionKey,
+    AccountId: params.route.accountId ?? params.accountId,
+    MessageSid: params.messageId,
+    MessageSidFull: params.messageIdFull,
+    ChatType: params.conversation.kind,
+    ConversationLabel: params.conversation.label,
+    GroupSubject: params.conversation.kind !== "direct" ? params.conversation.label : undefined,
+    GroupSystemPrompt: params.supplemental?.groupSystemPrompt,
+    SenderName: params.sender.name ?? params.sender.displayLabel,
+    SenderId: params.sender.id,
+    Timestamp: params.timestamp,
+    Provider: params.provider ?? params.channel,
+    Surface: params.surface ?? params.provider ?? params.channel,
+    WasMentioned: params.access?.mentions?.wasMentioned,
+    MentionedUserIds: params.access?.mentions?.mentionedUserIds,
+    OriginatingChannel: params.channel,
+    OriginatingTo: params.reply.originatingTo,
+  };
+}
+
+async function completeHandshake(
+  transport: MockTransport,
+  challengeTraceId = "challenge-bootstrap",
+  helloPayload: Record<string, unknown> = {},
+): Promise<Record<string, unknown>> {
+  await Promise.resolve();
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: challengeTraceId,
+      emitted_at: Date.now(),
+      payload: { nonce: `${challengeTraceId}-nonce` },
+    }),
+  );
+  const connectFrame = transport.sent
+    .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+    .filter((env) => env.event === "connect")
+    .at(-1)!;
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: connectFrame.trace_id,
+      emitted_at: Date.now(),
+      payload: helloPayload,
+    }),
+  );
+  await Promise.resolve();
+  return connectFrame;
+}
+
+function jsonEnvelope(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function conversationDetails(id: string, overrides: Record<string, unknown> = {}) {
+  return {
+    id,
+    type: "group",
+    title: `Room ${id}`,
+    description: `Description ${id}`,
+    creator_id: "user-owner",
+    created_at: "2026-05-21T10:00:00.000Z",
+    updated_at: "2026-05-21T10:01:00.000Z",
+    participants: [
+      {
+        conversation_id: id,
+        user_id: "user-owner",
+        role: "owner",
+        joined_at: "2026-05-21T10:00:30.000Z",
+        nickname: "Owner",
+        avatar_url: "https://cdn.example/owner.png",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function tempMemoryRoot(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-clawchat-runtime-"));
+}
+
+function createTestMemoryAgent(memoryRoot = tempMemoryRoot()) {
+  return {
+    resolveAgentWorkspaceDir: vi.fn(() => memoryRoot),
+  };
+}
+
+function buildNoDispatchRuntime(
+  dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined),
+  memoryRoot = tempMemoryRoot(),
+) {
+  return {
+    agent: createTestMemoryAgent(memoryRoot),
+    channel: {
+      routing: {
+        resolveAgentRoute: vi.fn(() => ({
+          agentId: "default",
+          accountId: "default",
+          sessionKey: "session-from-route",
+        })),
+      },
+      session: {
+        resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+        recordInboundSession: vi.fn().mockResolvedValue(undefined),
+      },
+      reply: {
+        formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+        resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+        finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+        resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+        createReplyDispatcherWithTyping: vi.fn(() => ({
+          dispatcher: {},
+          replyOptions: {},
+          markDispatchIdle: vi.fn(),
+          markRunComplete: vi.fn(),
+        })),
+        withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+        dispatchReplyFromConfig,
+      },
+      turn: {
+        buildContext: vi.fn((params) =>
+          buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+        ),
+      },
+      media: {
+        fetchRemoteMedia: vi.fn(),
+        saveMediaBuffer: vi.fn(),
+        loadWebMedia: vi.fn(),
+      },
+    },
+  } as unknown as PluginRuntime;
+}
+
+function inboundMessageEnvelope(params: {
+  chatId: string;
+  chatType: "direct" | "group";
+  messageId: string;
+  senderId: string;
+  text: string;
+  traceId?: string;
+  mentions?: unknown[];
+  emittedAt?: number;
+  senderType?: "agent" | "user" | "direct";
+}) {
+  return {
+    version: "2",
+    event: "message.send",
+    trace_id: params.traceId ?? `trace-${params.messageId}`,
+    emitted_at: params.emittedAt ?? Date.now(),
+    chat_id: params.chatId,
+    chat_type: params.chatType,
+    to: { id: "u", type: params.chatType },
+    sender: {
+      id: params.senderId,
+      type: params.senderType ?? "direct",
+      nick_name: params.senderId.replace(/^u(\d+)$/, "user-$1"),
+    },
+    payload: {
+      message_id: params.messageId,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text: params.text }] },
+        context: { mentions: params.mentions ?? [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    },
+  };
+}
+
+function mockMetadataFetches() {
+  return vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+    const url = String(input);
+    const userMatch = url.match(/\/v1\/users\/([^/?#]+)$/);
+    if (userMatch) {
+      const userId = decodeURIComponent(userMatch[1]!);
+      return jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          id: userId,
+          type: userId.includes("agent") ? "agent" : "user",
+          nickname: `User ${userId}`,
+          avatar_url: `https://cdn.example/${userId}.png`,
+          bio: `Bio ${userId}`,
+          updated_at: "2026-05-24T01:00:00.000Z",
+        },
+      });
+    }
+    const conversationMatch = url.match(/\/v1\/conversations\/([^/?#]+)$/);
+    if (conversationMatch) {
+      const groupId = decodeURIComponent(conversationMatch[1]!);
+      return jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          conversation: conversationDetails(groupId, {
+            participants: [
+              {
+                conversation_id: groupId,
+                user_id: "participant-1",
+                role: "member",
+                joined_at: "2026-05-24T01:01:00.000Z",
+              },
+              {
+                conversation_id: groupId,
+                user_id: "participant-agent",
+                role: "member",
+                joined_at: "2026-05-24T01:02:00.000Z",
+              },
+            ],
+          }),
+        },
+      });
+    }
+    const agentMatch = url.match(/\/v1\/agents\/([^/?#]+)$/);
+    if (agentMatch) {
+      const agentId = decodeURIComponent(agentMatch[1]!);
+      return jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          agent: {
+            id: agentId,
+            user_id: "u",
+            owner_id: "owner-u",
+            nickname: "Hermes",
+            avatar_url: "https://cdn.example/hermes.png",
+            bio: "Agent bio",
+            behavior: "Use current owner metadata.",
+            updated_at: "2026-05-24T01:03:00.000Z",
+          },
+        },
+      });
+    }
+    return new Response("unexpected test URL", { status: 500 });
+  });
+}
+
+describe("openclaw-clawchat runtime memory metadata refresh", () => {
+  it("activation success pulls owner metadata into owner.md", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    let bootstrapClaimed = false;
+    const store = {
+      startConnection: vi.fn(() => 501),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimPendingActivationBootstrap: vi.fn(() => {
+        if (bootstrapClaimed) return null;
+        bootstrapClaimed = true;
+        return { conversationId: "dm-activation" };
+      }),
+      releaseActivationBootstrapClaim: vi.fn(),
+      markActivationBootstrapSent: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-activation-owner-metadata");
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+      expect(ownerFile.metadata).toMatchObject({
+        agent_id: "u",
+        owner_id: "owner-u",
+        nickname: "Hermes",
+        behavior: "Use current owner metadata.",
+      });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/agents/agt-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("ordinary direct message pulls sender user metadata", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    const store = {
+      startConnection: vi.fn(() => 502),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => null),
+      upsertConversationSummary: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-direct-user-metadata");
+      transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+        chatId: "dm-user",
+        chatType: "direct",
+        messageId: "msg-user-metadata",
+        senderId: "user-1",
+        text: "hello",
+      })));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const userFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "user-1" });
+      expect(userFile.metadata).toMatchObject({
+        id: "user-1",
+        nickname: "User user-1",
+        avatar_url: "https://cdn.example/user-1.png",
+        bio: "Bio user-1",
+        profile_type: "user",
+      });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/users/user-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("owner direct message does not inject users owner metadata", async () => {
+    const memoryRoot = tempMemoryRoot();
+    await writeClawChatMetadata(memoryRoot, { targetType: "owner", targetId: "owner" }, {
+      agent_id: "u",
+      owner_id: "owner-u",
+      nickname: "Hermes",
+      behavior: "Use owner metadata.",
+    });
+    const handlers = new Map<string, Function>();
+    registerClawChatPromptInjection({
+      on: vi.fn((name: string, handler: Function) => handlers.set(name, handler)),
+    });
+    let promptBuildResult: unknown;
+    const dispatchReplyFromConfig = vi.fn(async () => {
+      promptBuildResult = await handlers.get("before_prompt_build")?.({}, { sessionKey: "session-from-route" });
+    });
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig, memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    const store = {
+      startConnection: vi.fn(() => 503),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({ conversationId: "dm-owner" })),
+      claimMessageOnce: vi.fn(() => true),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-owner-direct-metadata");
+      transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+        chatId: "dm-owner",
+        chatType: "direct",
+        messageId: "msg-owner-metadata",
+        senderId: "owner-u",
+        text: "hello",
+      })));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const ownerUserFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "owner-u" });
+      const directPrompt = (promptBuildResult as { appendSystemContext?: string }).appendSystemContext;
+      expect(ownerUserFile.exists).toBe(false);
+      expect(directPrompt).toContain("## Current ClawChat Owner Metadata");
+      expect(directPrompt).not.toContain("## Current ClawChat User Metadata");
+      expect(fetchMock).not.toHaveBeenCalledWith(
+        "https://api.example.com/v1/users/owner-u",
+        expect.anything(),
+      );
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("first group message pulls group metadata and participant users", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    const store = {
+      startConnection: vi.fn(() => 504),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => null),
+      upsertConversationSummary: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-group-metadata");
+      transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+        chatId: "grp-memory",
+        chatType: "group",
+        messageId: "msg-group-metadata",
+        senderId: "participant-1",
+        text: "hello group",
+        mentions: ["u"],
+      })));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "grp-memory" });
+      const participantFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "participant-1" });
+      const participantAgentFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "participant-agent" });
+      expect(groupFile.metadata).toMatchObject({
+        id: "grp-memory",
+        title: "Room grp-memory",
+        description: "Description grp-memory",
+      });
+      expect(participantFile.metadata).toMatchObject({
+        id: "participant-1",
+      });
+      expect(participantAgentFile.metadata).toMatchObject({
+        id: "participant-agent",
+      });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/grp-memory",
+        expect.objectContaining({ method: "GET" }),
+      );
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("group messages refresh group metadata even when the conversation is cached", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    const store = {
+      startConnection: vi.fn(() => 505),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({ conversationId: "grp-cached" })),
+      upsertConversationSummary: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-group-cached-metadata");
+      transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+        chatId: "grp-cached",
+        chatType: "group",
+        messageId: "msg-group-cached-metadata",
+        senderId: "participant-1",
+        text: "hello cached group",
+        mentions: ["u"],
+      })));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/grp-cached",
+        expect.objectContaining({ method: "GET" }),
+      );
+      const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "grp-cached" });
+      const participantFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "participant-1" });
+      expect(groupFile.metadata).toMatchObject({
+        id: "grp-cached",
+        title: "Room grp-cached",
+      });
+      expect(participantFile.metadata).toMatchObject({
+        id: "participant-1",
+      });
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("metadata invalidation behavior scope pulls owner metadata", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined);
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig, memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    const store = {
+      startConnection: vi.fn(() => 505),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-behavior-file-metadata");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-owner-file",
+        emitted_at: Date.now(),
+        chat_id: "dm-owner",
+        chat_type: "direct",
+        payload: { scope: ["behavior"], version: 3 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+      expect(ownerFile.metadata).toMatchObject({
+        agent_id: "u",
+        behavior: "Use current owner metadata.",
+      });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/agents/agt-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it.each([
+    ["title", ["title"]],
+    ["description", ["description"]],
+    ["unknown", ["unknown"]],
+    ["empty", []],
+  ])("metadata invalidation %s scope pulls group metadata", async (_name, scope) => {
+    const memoryRoot = tempMemoryRoot();
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined);
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig, memoryRoot);
+    const fetchMock = mockMetadataFetches();
+    const store = {
+      startConnection: vi.fn(() => 506),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, `challenge-group-file-${_name}`);
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: `meta-group-file-${_name}`,
+        emitted_at: Date.now(),
+        chat_id: `grp-${_name}`,
+        chat_type: "group",
+        payload: { scope, version: 4 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: `grp-${_name}` });
+      expect(groupFile.metadata).toMatchObject({
+        id: `grp-${_name}`,
+        title: `Room grp-${_name}`,
+      });
+      expect(fetchMock).toHaveBeenCalledWith(
+        `https://api.example.com/v1/conversations/grp-${_name}`,
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+});
+
 describe("openclaw-clawchat runtime helpers", () => {
-  it("maps SDK states to channel status shape", () => {
+  it("maps local client states to channel status shape", () => {
     expect(mapClawlingStateToStatus("connected")).toMatchObject({
       connected: true,
       running: true,
@@ -62,7 +801,7 @@ describe("openclaw-clawchat runtime helpers", () => {
   });
 
   it("classifies AuthError as fatal/no-retry", () => {
-    const c = classifyClawlingClientError(new AuthError("hello-fail", "bad-token"));
+    const c = classifyClawlingClientError(new AuthError("bad-token"));
     expect(c.kind).toBe("auth");
     expect(c.retry).toBe(false);
   });
@@ -79,6 +818,40 @@ describe("openclaw-clawchat runtime helpers", () => {
     expect(getOpenclawClawlingRuntime()).toBe(rt);
   });
 
+  it("memory workspace accepts workspace_xxx roots from OpenClaw", () => {
+    const cfg = {} as OpenClawConfig;
+    const runtime = {
+      agent: {
+        resolveAgentWorkspaceDir: vi.fn(() => ".openclaw/workspace_01JABC"),
+      },
+    } as unknown as PluginRuntime;
+
+    expect(resolveClawChatMemoryRoot(runtime, cfg, "agent-a")).toBe(".openclaw/workspace_01JABC");
+    expect(runtime.agent.resolveAgentWorkspaceDir).toHaveBeenCalledWith(cfg, "agent-a");
+  });
+
+  it("memory workspace fails visibly when OpenClaw workspaceDir is missing", () => {
+    const cfg = {} as OpenClawConfig;
+    const runtime = {
+      agent: {
+        resolveAgentWorkspaceDir: vi.fn(() => "   "),
+      },
+    } as unknown as PluginRuntime;
+
+    expect(() => resolveClawChatMemoryRoot(runtime, cfg, "agent-a")).toThrow(
+      "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved",
+    );
+  });
+
+  it("memory workspace does not fall back to the plugin package directory", () => {
+    const cfg = {} as OpenClawConfig;
+    const runtime = {} as unknown as PluginRuntime;
+
+    expect(() => resolveClawChatMemoryRoot(runtime, cfg, "agent-a")).toThrow(
+      "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved",
+    );
+  });
+
   it("logs auth_failed and does not reconnect after hello-fail", async () => {
     const logs: string[] = [];
     const transport = new MockTransport();
@@ -206,10 +979,19 @@ describe("openclaw-clawchat runtime helpers", () => {
     await run;
   });
 
-  it("logs handshake_ok with the connect trace when hello-ok trace_id differs", async () => {
-    const logs: string[] = [];
+  it("records websocket lifecycle calls in connection order", async () => {
+    const calls: string[] = [];
     const transport = new MockTransport();
     const abortController = new AbortController();
+    const store = {
+      startConnection: vi.fn(() => {
+        calls.push("startConnection");
+        return 101;
+      }),
+      markConnectSent: vi.fn(() => calls.push("markConnectSent")),
+      markConnectionReady: vi.fn(() => calls.push("markConnectionReady")),
+      finishConnection: vi.fn((_id, input) => calls.push(`finishConnection:${input.state}`)),
+    };
 
     setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
     const run = startOpenclawClawlingGateway({
@@ -218,8 +1000,9 @@ describe("openclaw-clawchat runtime helpers", () => {
       abortSignal: abortController.signal,
       setStatus: () => {},
       getStatus: () => ({ connected: false, configured: true, running: true }),
-      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      log: { info: vi.fn(), error: vi.fn() },
       transport,
+      store,
     });
 
     await Promise.resolve();
@@ -239,32 +1022,47 @@ describe("openclaw-clawchat runtime helpers", () => {
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "hello-different",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
     );
     await Promise.resolve();
 
-    expect(logs).toContainEqual(
-      expect.stringMatching(
-        new RegExp(
-          "^clawchat\\.ws event=handshake_ok account_id=default attempt=1 reconnect_count=0 state=ready action=flush_queue trace_id=" +
-            connectFrame.trace_id +
-            " elapsed_ms=\\d+ queue_size=0$",
-        ),
-      ),
-    );
-    expect(logs.some((line) => line.includes("trace_id=hello-different elapsed_ms="))).toBe(false);
-
     abortController.abort();
     await run;
+
+    expect(calls).toEqual([
+      "startConnection",
+      "markConnectSent",
+      "markConnectionReady",
+      "finishConnection:disconnected",
+    ]);
+    expect(store.startConnection).toHaveBeenCalledWith(
+      expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        attempt: 1,
+        reconnectCount: 0,
+      }),
+    );
+    expect(store.markConnectSent).toHaveBeenCalledWith(101);
+    expect(store.markConnectionReady).toHaveBeenCalledWith(101);
+    expect(store.finishConnection).toHaveBeenCalledWith(
+      101,
+      expect.objectContaining({ state: "disconnected", closeCode: 1000 }),
+    );
   });
 
-  it("logs JSON ping and pong as protocol control", async () => {
-    const logs: string[] = [];
+  it("records hello-ok device metadata when marking a connection ready", async () => {
     const transport = new MockTransport();
     const abortController = new AbortController();
+    const store = {
+      startConnection: vi.fn(() => 111),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
 
     setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
     const run = startOpenclawClawlingGateway({
@@ -273,8 +1071,9 @@ describe("openclaw-clawchat runtime helpers", () => {
       abortSignal: abortController.signal,
       setStatus: () => {},
       getStatus: () => ({ connected: false, configured: true, running: true }),
-      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      log: { info: vi.fn(), error: vi.fn() },
       transport,
+      store,
     });
 
     await Promise.resolve();
@@ -296,117 +1095,984 @@ describe("openclaw-clawchat runtime helpers", () => {
         event: "hello-ok",
         trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
-        payload: {},
+        payload: { device_id: "device-resolved", delivery_mode: "device_replay" },
       }),
     );
     await Promise.resolve();
-    transport.sent.length = 0;
 
-    transport.emitInbound(
-      JSON.stringify({
-        version: "2",
-        event: "ping",
-        trace_id: "trace-ping",
-        emitted_at: Date.now(),
-        payload: {},
+    abortController.abort();
+    await run;
+
+    expect(store.markConnectionReady).toHaveBeenCalledWith(
+      111,
+      expect.objectContaining({
+        resolvedDeviceId: "device-resolved",
+        deliveryMode: "device_replay",
       }),
     );
-    transport.emitInbound(
-      JSON.stringify({
+  });
+
+  it("refreshes metadata invalidations without dispatching an agent turn", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined);
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig, memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("group-1") } }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 121),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-1",
+        conversationType: "group",
+        metadataVersion: 4,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-refresh");
+      transport.emitInbound(JSON.stringify({
         version: "2",
-        event: "pong",
-        trace_id: "trace-pong",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-refresh",
         emitted_at: Date.now(),
-        payload: {},
-      }),
-    );
+        chat_id: "group-1",
+        chat_type: "group",
+        payload: { scope: ["unknown"], version: 7 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 30));
 
-    expect(transport.sent.map((raw) => JSON.parse(raw))).toContainEqual(
-      expect.objectContaining({ event: "pong", trace_id: "trace-ping" }),
-    );
-    expect(logs).toContain(
-      "clawchat.ws event=protocol_ping_received account_id=default attempt=1 reconnect_count=0 state=ready action=send_pong trace_id=trace-ping",
-    );
-    expect(logs).toContain(
-      "clawchat.ws event=protocol_pong_received account_id=default attempt=1 reconnect_count=0 state=ready action=ignore trace_id=trace-pong",
-    );
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/group-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        conversationId: "group-1",
+        conversationType: "group",
+        metadataVersion: 7,
+        members: [expect.objectContaining({ userId: "user-owner", role: "owner" })],
+        membersComplete: true,
+      }));
+      await expect(readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "group-1" }))
+        .resolves.toMatchObject({ metadata: expect.objectContaining({ title: "Room group-1" }) });
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
 
-    abortController.abort();
-    await run;
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
   });
 
-  it("logs unknown ready-state events as inbound_ignored", async () => {
+  it("logs metadata invalidations without chat_id and treats stale versions as pull signals", async () => {
     const logs: string[] = [];
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("group-stale") } }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 122),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-stale",
+        conversationType: "group",
+        metadataVersion: 9,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+    };
     const transport = new MockTransport();
     const abortController = new AbortController();
 
-    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
-    const run = startOpenclawClawlingGateway({
-      cfg: {},
-      account: baseAccount(),
-      abortSignal: abortController.signal,
-      setStatus: () => {},
-      getStatus: () => ({ connected: false, configured: true, running: true }),
-      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
-      transport,
-    });
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
 
-    await Promise.resolve();
-    transport.emitInbound(
-      JSON.stringify({
+      await completeHandshake(transport, "challenge-meta-stale");
+      transport.emitInbound(JSON.stringify({
         version: "2",
-        event: "connect.challenge",
-        trace_id: "challenge-1",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-missing-chat",
         emitted_at: Date.now(),
-        payload: { nonce: "nonce-1" },
-      }),
-    );
-    const connectFrame = transport.sent
-      .map((raw) => JSON.parse(raw))
-      .find((env) => env.event === "connect");
-    transport.emitInbound(
-      JSON.stringify({
+        payload: { version: 10 },
+      }));
+      transport.emitInbound(JSON.stringify({
         version: "2",
-        event: "hello-ok",
-        trace_id: connectFrame.trace_id,
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-stale",
         emitted_at: Date.now(),
-        payload: {},
-      }),
-    );
-    await Promise.resolve();
+        chat_id: "group-stale",
+        payload: { version: 9 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 30));
 
-    transport.emitInbound(
-      JSON.stringify({
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/group-stale",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "group-stale",
+      }));
+      expect(logs.some((line) => line.includes("metadata invalidation missing chat_id"))).toBe(true);
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("refreshes metadata invalidations without a version and deletes scoped cache on not found", async () => {
+    const runtime = buildNoDispatchRuntime();
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = String(input);
+      if (url.endsWith("/v1/conversations/group-no-version")) {
+        return jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("group-no-version") } });
+      }
+      if (url.endsWith("/v1/users/user-owner")) {
+        return jsonEnvelope({ code: 0, msg: "ok", data: { id: "user-owner", nickname: "Owner" } });
+      }
+      if (url.endsWith("/v1/conversations/group-missing")) {
+        return jsonEnvelope({ code: 404, msg: "conversation not found", data: {} });
+      }
+      return jsonEnvelope({ code: 0, msg: "ok", data: { agent: { id: "agt-1" } } });
+    });
+    const store = {
+      startConnection: vi.fn(() => 123),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-no-version",
+        conversationType: "group",
+        metadataVersion: 99,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-noversion");
+      transport.emitInbound(JSON.stringify({
         version: "2",
-        event: "custom.event",
-        trace_id: "trace-custom",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-no-version",
         emitted_at: Date.now(),
+        chat_id: "group-no-version",
         payload: {},
-      }),
-    );
+      }));
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-not-found",
+        emitted_at: Date.now(),
+        chat_id: "group-missing",
+        payload: { version: 100 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
 
-    expect(logs).toContain(
-      "clawchat.ws event=inbound_ignored account_id=default attempt=1 reconnect_count=0 state=ready action=ignore event_name=custom.event trace_id=trace-custom",
-    );
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "group-no-version",
+      }));
+      expect(store.deleteConversationCache).toHaveBeenCalledWith({
+        platform: "openclaw",
+        accountId: "default",
+        conversationId: "group-missing",
+      });
 
-    abortController.abort();
-    await run;
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
   });
 
-  it("auto flushes queued outbound when runtime observes connected", async () => {
-    const logs: string[] = [];
+  it("clears group description on metadata invalidation when conversation detail returns explicit null", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: { conversation: conversationDetails("group-clear-description", { description: null }) },
+      }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 126),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-clear-description",
+        conversationType: "group",
+        metadataVersion: 5,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+    };
     const transport = new MockTransport();
     const abortController = new AbortController();
 
-    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-description-null");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-description-null",
+        emitted_at: Date.now(),
+        chat_id: "group-clear-description",
+        payload: { scope: ["description"], version: 6 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "group-clear-description",
+      }));
+      const groupFile = await readClawChatMemoryFile(memoryRoot, {
+        targetType: "group",
+        targetId: "group-clear-description",
+      });
+      expect(groupFile.metadata).toMatchObject({ id: "group-clear-description" });
+      expect(groupFile.metadata).not.toHaveProperty("description");
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("refreshes behavior invalidations from the agent endpoint and stores behavior in owner metadata", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          agent: {
+            id: "agent-row",
+            user_id: "u",
+            owner_id: "owner-u",
+            type: "agent",
+            nickname: "Hermes",
+            avatar_url: "https://example.test/hermes.png",
+            bio: "Agent bio",
+            behavior: "Use updated behavior.",
+          },
+        },
+      }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 127),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-behavior-meta");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-behavior",
+        emitted_at: Date.now(),
+        chat_id: "dm-owner-agent",
+        chat_type: "direct",
+        payload: { scope: ["behavior"], version: 6 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/agents/agt-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(fetchMock).not.toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/dm-owner-agent",
+        expect.anything(),
+      );
+      const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+      expect(ownerFile.metadata).toMatchObject({
+        agent_id: "u",
+        owner_id: "owner-u",
+        nickname: "Hermes",
+        avatar_url: "https://example.test/hermes.png",
+        bio: "Agent bio",
+        behavior: "Use updated behavior.",
+      });
+      expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("clears behavior on metadata invalidation when the agent endpoint returns explicit null", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          agent: {
+            user_id: "u",
+            owner_id: "owner-u",
+            type: "agent",
+            nickname: "Hermes",
+            behavior: null,
+          },
+        },
+      }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 132),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-behavior-null-meta");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-behavior-null",
+        emitted_at: Date.now(),
+        chat_id: "dm-owner-agent",
+        chat_type: "direct",
+        payload: { scope: ["behavior"], version: 6 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+      expect(ownerFile.metadata).toMatchObject({
+        agent_id: "u",
+        owner_id: "owner-u",
+        nickname: "Hermes",
+      });
+      expect(ownerFile.metadata).not.toHaveProperty("behavior");
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("ordinary direct messages refresh user metadata on each message", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const requestedUrls: string[] = [];
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      requestedUrls.push(String(input));
+      const requestNumber = requestedUrls.length;
+      return jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          id: "user-1",
+          type: "user",
+          nickname: requestNumber === 1 ? "User One" : "User One Updated",
+          avatar_url: "https://example.test/u.png",
+          bio: requestNumber === 1 ? "Bio" : "Updated Bio",
+        },
+      });
+    });
+    const knownChats = new Set<string>();
+    const store = {
+      startConnection: vi.fn(() => 128),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn((input: { conversationId: string }) =>
+        knownChats.has(input.conversationId) ? { conversationId: input.conversationId } : null
+      ),
+      upsertConversationSummary: vi.fn((input: { conversationId: string }) => knownChats.add(input.conversationId)),
+      upsertConversationDetails: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-direct-profile");
+      for (const messageId of ["m-direct-1", "m-direct-2"]) {
+        transport.emitInbound(JSON.stringify({
+          version: "2",
+          event: "message.send",
+          trace_id: messageId,
+          emitted_at: Date.now(),
+          chat_id: "dm-1",
+          chat_type: "direct",
+          sender: { id: "user-1", type: "direct", nick_name: "User One" },
+          payload: {
+            message_id: messageId,
+            message_mode: "normal",
+            message: {
+              body: { fragments: [{ kind: "text", text: "hello" }] },
+              context: { mentions: [], reply: null },
+              streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+            },
+          },
+        }));
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+
+      expect(requestedUrls).toEqual([
+        "https://api.example.com/v1/users/user-1",
+        "https://api.example.com/v1/users/user-1",
+      ]);
+      const userFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "user-1" });
+      expect(userFile.metadata).toMatchObject({
+        id: "user-1",
+        nickname: "User One Updated",
+        avatar_url: "https://example.test/u.png",
+        bio: "Updated Bio",
+        profile_type: "user",
+      });
+      expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("waits for first-seen user detail before building the direct prompt", async () => {
+    const handlers = new Map<string, Function>();
+    registerClawChatPromptInjection({
+      on: vi.fn((name: string, handler: Function) => handlers.set(name, handler)),
+    });
+    let promptBuildResult: unknown;
+    const dispatchReplyFromConfig = vi.fn(async () => {
+      promptBuildResult = await handlers.get("before_prompt_build")?.({}, { sessionKey: "session-from-route" });
+    });
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+    const requestedUrls: string[] = [];
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      requestedUrls.push(String(input));
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      return jsonEnvelope({
+        code: 0,
+        msg: "ok",
+        data: {
+          id: "user-1",
+          type: "user",
+          nickname: "Fetched User",
+          avatar_url: "https://example.test/fetched.png",
+          bio: "Fetched bio",
+        },
+      });
+    });
+    const store = {
+      startConnection: vi.fn(() => 130),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => null),
+      upsertConversationSummary: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-direct-prompt-profile");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "m-direct-prompt-profile",
+        emitted_at: Date.now(),
+        chat_id: "dm-1",
+        chat_type: "direct",
+        sender: { id: "user-1", type: "direct", nick_name: "Fallback User" },
+        payload: {
+          message_id: "m-direct-prompt-profile",
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello" }] },
+            context: { mentions: [], reply: null },
+            streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+          },
+        },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 80));
+
+      expect(requestedUrls).toEqual(["https://api.example.com/v1/users/user-1"]);
+      expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+      const directPrompt = (promptBuildResult as { appendSystemContext?: string }).appendSystemContext;
+      expect(directPrompt).toContain("## Current ClawChat User Metadata");
+      expect(directPrompt).toContain("nickname: Fetched User");
+      expect(directPrompt).toContain("avatar_url: https://example.test/fetched.png");
+      expect(directPrompt).toContain("bio: Fetched bio");
+      expect(directPrompt).toContain("chat_type: dm");
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("uses dm plus sender_is_owner for owner direct messages", async () => {
+    const handlers = new Map<string, Function>();
+    registerClawChatPromptInjection({
+      on: vi.fn((name: string, handler: Function) => handlers.set(name, handler)),
+    });
+    let promptBuildResult: unknown;
+    const dispatchReplyFromConfig = vi.fn(async () => {
+      promptBuildResult = await handlers.get("before_prompt_build")?.({}, { sessionKey: "session-from-route" });
+    });
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+    const store = {
+      startConnection: vi.fn(() => 131),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({ conversationId: "dm-owner" })),
+      upsertConversationSummary: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime(runtime);
     const run = startOpenclawClawlingGateway({
       cfg: {},
-      account: baseAccount({ ack: { timeout: 15000, autoResendOnTimeout: false } }),
+      account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await completeHandshake(transport, "challenge-owner-dm-prompt");
+    transport.emitInbound(JSON.stringify({
+      version: "2",
+      event: "message.send",
+      trace_id: "m-owner-dm-prompt",
+      emitted_at: Date.now(),
+      chat_id: "dm-owner",
+      chat_type: "direct",
+      sender: { id: "owner-u", type: "direct", nick_name: "Owner" },
+      payload: {
+        message_id: "m-owner-dm-prompt",
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "hello" }] },
+          context: { mentions: [], reply: null },
+          streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+        },
+      },
+    }));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    abortController.abort();
+    await run;
+
+    const directPrompt = (promptBuildResult as { appendSystemContext?: string }).appendSystemContext;
+    expect(directPrompt).toContain("chat_type: dm");
+    expect(directPrompt).toContain("sender_is_owner: true");
+    expect(directPrompt).not.toContain("owner_dm");
+    expect(directPrompt).not.toContain("sender_relation:");
+  });
+
+  it("first group metadata sync fetches conversation detail and saves group metadata", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("grp-profile") } }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 129),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => null),
+      upsertConversationSummary: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount({ userId: "u", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-group-profile");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "m-group-profile",
+        emitted_at: Date.now(),
+        chat_id: "grp-profile",
+        chat_type: "group",
+        sender: { id: "user-1", type: "direct", nick_name: "User One" },
+        payload: {
+          message_id: "m-group-profile",
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello group" }] },
+            context: { mentions: ["u"], reply: null },
+            streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+          },
+        },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 30));
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/grp-profile",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/users/user-owner",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "grp-profile",
+      }));
+      const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "grp-profile" });
+      expect(groupFile.metadata).toMatchObject({
+        id: "grp-profile",
+        title: "Room grp-profile",
+      });
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("logs metadata refresh errors without advancing the cached version", async () => {
+    const logs: string[] = [];
+    const runtime = buildNoDispatchRuntime();
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("gateway unavailable", { status: 500 }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 124),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-error",
+        conversationType: "group",
+        metadataVersion: 1,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-error");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-error",
+        emitted_at: Date.now(),
+        chat_id: "group-error",
+        payload: { version: 2 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+      expect(store.deleteConversationCache).not.toHaveBeenCalled();
+      expect(logs.some((line) => line.includes("metadata refresh failed"))).toBe(true);
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("refreshes activation and cached conversations after hello-ok without writing tool calls", async () => {
+    const runtime = buildNoDispatchRuntime();
+    const requestedIds: string[] = [];
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const id = String(input).split("/").at(-1)!;
+      requestedIds.push(id);
+      if (id === "cached-fail") {
+        return new Response("oops", { status: 500 });
+      }
+      return jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails(id) } });
+    });
+    const cachedIds = ["cached-1", "activation-1", "cached-fail", ...Array.from({ length: 25 }, (_, i) => `cached-${i + 2}`)];
+    const store = {
+      startConnection: vi.fn(() => 125),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getActivationConversation: vi.fn(() => ({
+        conversationId: "activation-1",
+        conversationType: "direct",
+        metadataVersion: null,
+        lastSeenAt: null,
+        lastRefreshedAt: null,
+      })),
+      listCachedConversationIds: vi.fn(() => cachedIds),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+      recordToolCall: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-fresh-fetch");
+      await new Promise((resolve) => setTimeout(resolve, 30));
+
+      expect(store.listCachedConversationIds).toHaveBeenCalledWith({
+        platform: "openclaw",
+        accountId: "default",
+        limit: 20,
+      });
+      expect(requestedIds[0]).toBe("activation-1");
+      expect(requestedIds.filter((id) => id === "activation-1")).toHaveLength(1);
+      expect(requestedIds).toContain("cached-1");
+      expect(requestedIds).toContain("cached-fail");
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "cached-1",
+      }));
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "cached-2",
+      }));
+      expect(store.recordToolCall).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("records auth failure and transport error as terminal connection states", async () => {
+    const authTransport = new MockTransport();
+    const authStore = {
+      startConnection: vi.fn(() => 201),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const authRun = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: new AbortController().signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport: authTransport,
+      store: authStore,
+    });
+
+    await Promise.resolve();
+    authTransport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-auth",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const authConnectFrame = authTransport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    authTransport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-fail",
+        trace_id: authConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: { reason: "authentication failed" },
+      }),
+    );
+
+    await authRun;
+
+    expect(authStore.finishConnection).toHaveBeenCalledWith(
+      201,
+      expect.objectContaining({ state: "auth_failed", error: "authentication failed" }),
+    );
+
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const transportStore = {
+      startConnection: vi.fn(() => 301),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+    const transportRun = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
       abortSignal: abortController.signal,
       setStatus: () => {},
       getStatus: () => ({ connected: false, configured: true, running: true }),
-      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      log: { info: vi.fn(), error: vi.fn() },
       transport,
+      store: transportStore,
     });
 
     await Promise.resolve();
@@ -414,77 +2080,90 @@ describe("openclaw-clawchat runtime helpers", () => {
       JSON.stringify({
         version: "2",
         event: "connect.challenge",
-        trace_id: "challenge-1",
+        trace_id: "challenge-transport",
         emitted_at: Date.now(),
         payload: { nonce: "nonce-1" },
       }),
     );
-    const connectFrame = transport.sent
+    const transportConnectFrame = transport.sent
       .map((raw) => JSON.parse(raw))
       .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: connectFrame.trace_id,
+        trace_id: transportConnectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
     );
     await Promise.resolve();
-
-    const client = getOpenclawClawlingClient("default")!;
-    transport.close(1006, "network lost");
+    transport.emitError(new Error("socket down"));
     await Promise.resolve();
+    abortController.abort();
+    await transportRun;
 
-    let sendResult: unknown;
-    const sendPromise = sendOpenclawClawlingText({
-      client,
-      account: baseAccount({ ack: { timeout: 15000, autoResendOnTimeout: false } }),
-      to: { chatId: "chat-1", chatType: "direct" },
-      text: "queued while reconnecting",
-      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
-    }).then((result) => {
-      sendResult = result;
-      return result;
-    });
-    await Promise.resolve();
+    expect(transportStore.finishConnection).toHaveBeenCalledWith(
+      301,
+      expect.objectContaining({ state: "transport_error", error: "socket down" }),
+    );
+  });
 
-    const sentBeforeReady = transport.sent.length;
-    expect(logs.some((line) => line.includes("event=send_queued"))).toBe(true);
+  it("logs handshake_ok with the connect trace", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
 
-    (transport as unknown as { _state: string })._state = "open";
-    client.emit("state", { from: "reconnecting", to: "connected" });
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
 
-    expect(logs).toContainEqual(
-      expect.stringMatching(
-        /^clawchat\.ws event=handshake_ok account_id=default attempt=1 reconnect_count=1 state=ready action=flush_queue trace_id=[^ ]+ elapsed_ms=\d+ queue_size=1$/,
-      ),
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
     );
-    expect(transport.sent.length).toBe(sentBeforeReady + 1);
-    const queuedFrame = JSON.parse(transport.sent.at(-1)!);
-    expect(queuedFrame.event).toBe("message.send");
-    expect(logs.some((line) => line.includes("event=send_flush"))).toBe(true);
-
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
-        event: "message.ack",
-        trace_id: queuedFrame.trace_id,
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
-        chat_id: "chat-1",
-        payload: { message_id: "server-1", accepted_at: 1234 },
+        payload: {},
       }),
     );
-    await sendPromise;
-    expect(sendResult).toEqual({ messageId: "server-1", acceptedAt: 1234 });
+    await Promise.resolve();
+
+    expect(logs).toContainEqual(
+      expect.stringMatching(
+        new RegExp(
+          "^clawchat\\.ws event=handshake_ok account_id=default attempt=1 reconnect_count=0 state=ready action=flush_queue trace_id=" +
+            connectFrame.trace_id +
+            " elapsed_ms=\\d+ queue_size=0$",
+        ),
+      ),
+    );
 
     abortController.abort();
     await run;
   });
 
-  it("uses real attempt and reconnect_count in websocket logs across reconnect", async () => {
-    vi.useFakeTimers();
+  it("logs JSON ping and pong as protocol control", async () => {
     const logs: string[] = [];
     const transport = new MockTransport();
     const abortController = new AbortController();
@@ -492,14 +2171,7 @@ describe("openclaw-clawchat runtime helpers", () => {
     setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
     const run = startOpenclawClawlingGateway({
       cfg: {},
-      account: baseAccount({
-        reconnect: {
-          initialDelay: 1000,
-          maxDelay: 30000,
-          jitterRatio: 0,
-          maxRetries: Number.POSITIVE_INFINITY,
-        },
-      }),
+      account: baseAccount(),
       abortSignal: abortController.signal,
       setStatus: () => {},
       getStatus: () => ({ connected: false, configured: true, running: true }),
@@ -517,21 +2189,282 @@ describe("openclaw-clawchat runtime helpers", () => {
         payload: { nonce: "nonce-1" },
       }),
     );
-    const firstConnectFrame = transport.sent
+    const connectFrame = transport.sent
       .map((raw) => JSON.parse(raw))
       .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: firstConnectFrame.trace_id,
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
     );
     await Promise.resolve();
+    transport.sent.length = 0;
 
-    transport.close(1006, "network lost");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "ping",
+        trace_id: "trace-ping",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "pong",
+        trace_id: "trace-pong",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+
+    expect(transport.sent.map((raw) => JSON.parse(raw))).toContainEqual(
+      expect.objectContaining({ event: "pong", trace_id: "trace-ping" }),
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=protocol_ping_received account_id=default attempt=1 reconnect_count=0 state=ready action=send_pong trace_id=trace-ping",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=protocol_pong_received account_id=default attempt=1 reconnect_count=0 state=ready action=ignore trace_id=trace-pong",
+    );
+
+    abortController.abort();
+    await run;
+  });
+
+  it("logs unknown ready-state events as inbound_ignored", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "custom.event",
+        trace_id: "trace-custom",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+
+    expect(logs).toContain(
+      "clawchat.ws event=inbound_ignored account_id=default attempt=1 reconnect_count=0 state=ready action=ignore event_name=custom.event trace_id=trace-custom",
+    );
+
+    abortController.abort();
+    await run;
+  });
+
+  it("auto flushes queued outbound when runtime observes connected", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const account = baseAccount({
+      ack: { timeout: 15000, autoResendOnTimeout: false },
+      reconnect: {
+        initialDelay: 1,
+        maxDelay: 1,
+        jitterRatio: 0,
+        maxRetries: Number.POSITIVE_INFINITY,
+      },
+    });
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account,
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    const client = getOpenclawClawlingClient("default")!;
+    transport.close(1006, "network lost");
+    await Promise.resolve();
+
+    let sendResult: unknown;
+    const sendPromise = sendOpenclawClawlingText({
+      client,
+      account,
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "queued while reconnecting",
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+    }).then((result) => {
+      sendResult = result;
+      return result;
+    });
+    await Promise.resolve();
+
+    const sentBeforeReady = transport.sent.length;
+    expect(logs.some((line) => line.includes("event=send_queued"))).toBe(true);
+
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-2",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-2" },
+      }),
+    );
+    const secondConnectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .filter((env) => env.event === "connect")
+      .at(-1);
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: secondConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    expect(logs).toContainEqual(
+      expect.stringMatching(
+        /^clawchat\.ws event=handshake_ok account_id=default attempt=2 reconnect_count=1 state=ready action=flush_queue trace_id=[^ ]+ elapsed_ms=\d+ queue_size=1$/,
+      ),
+    );
+    expect(transport.sent.length).toBe(sentBeforeReady + 2);
+    const queuedFrame = JSON.parse(transport.sent.at(-1)!);
+    expect(queuedFrame.event).toBe("message.send");
+    expect(logs.some((line) => line.includes("event=send_flush"))).toBe(true);
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.ack",
+        trace_id: queuedFrame.trace_id,
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        payload: { message_id: "server-1", accepted_at: 1234 },
+      }),
+    );
+    await sendPromise;
+    expect(sendResult).toEqual({ messageId: "server-1", acceptedAt: 1234 });
+
+    abortController.abort();
+    await run;
+  });
+
+  it("uses real attempt and reconnect_count in websocket logs across reconnect", async () => {
+    vi.useFakeTimers();
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount({
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+      }),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const firstConnectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: firstConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    transport.close(1006, "network lost");
     await Promise.resolve();
     expect(logs).toContain(
       "clawchat.ws event=connection_lost account_id=default attempt=1 reconnect_count=0 state=ready action=reconnect code=1006 reason=network lost",
@@ -566,52 +2499,1725 @@ describe("openclaw-clawchat runtime helpers", () => {
     );
     await Promise.resolve();
 
-    transport.emitInbound(
-      JSON.stringify({
-        version: "2",
-        event: "custom.event",
-        trace_id: "trace-after-reconnect",
-        emitted_at: Date.now(),
-        payload: {},
-      }),
-    );
-    expect(logs).toContain(
-      "clawchat.ws event=inbound_ignored account_id=default attempt=2 reconnect_count=1 state=ready action=ignore event_name=custom.event trace_id=trace-after-reconnect",
-    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "custom.event",
+        trace_id: "trace-after-reconnect",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=inbound_ignored account_id=default attempt=2 reconnect_count=1 state=ready action=ignore event_name=custom.event trace_id=trace-after-reconnect",
+    );
+
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(logs).toContain(
+      "clawchat.ws event=reconnect_backoff_reset account_id=default attempt=2 reconnect_count=0 state=ready action=reset stable_ms=5000",
+    );
+
+    abortController.abort();
+    await run;
+    vi.useRealTimers();
+  });
+});
+
+describe("openclaw-clawchat runtime media ingest", () => {
+  it("memory workspace passes active OpenClaw workspaceDir to the turn context", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const fetchMock = mockMetadataFetches();
+    let capturedContextParams:
+      | Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]
+      | undefined;
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined);
+    const runtime = {
+      agent: {
+        resolveAgentWorkspaceDir: vi.fn(() => memoryRoot),
+      },
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "agent-memory",
+            accountId: "default",
+            sessionKey: "session-memory",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) => {
+            capturedContextParams =
+              params as Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0];
+            return buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]);
+          }),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+    });
+
+    await completeHandshake(transport, "challenge-memory-workspace");
+    transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+      chatId: "chat-memory",
+      chatType: "direct",
+      messageId: "msg-memory",
+      senderId: "user-memory",
+      text: "remember this",
+    })));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    abortController.abort();
+    await run;
+
+    fetchMock.mockRestore();
+    expect(runtime.agent.resolveAgentWorkspaceDir).toHaveBeenCalledWith({}, "agent-memory");
+    expect(capturedContextParams?.extra).toEqual({
+      memoryRoot,
+    });
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it("memory workspace fails visibly on inbound turns when OpenClaw resolver is missing", async () => {
+    const logError = vi.fn();
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined);
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "agent-memory",
+            accountId: "default",
+            sessionKey: "session-memory",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: logError },
+      transport,
+    });
+
+    await completeHandshake(transport, "challenge-memory-missing-resolver");
+    transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+      chatId: "chat-memory-missing",
+      chatType: "direct",
+      messageId: "msg-memory-missing",
+      senderId: "user-memory",
+      text: "remember this",
+    })));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    abortController.abort();
+    await run;
+
+    expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved",
+      ),
+    );
+  });
+
+  it("claims complete inbound messages but not streaming created/add fragments", async () => {
+    const runtime = {
+      agent: createTestMemoryAgent(),
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "u",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
+            await opts.run();
+          }),
+          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 401),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      insertMessage: vi.fn(),
+      upsertConversationSummary: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+    };
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-inbound-persist",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    for (const event of ["message.created", "message.add"]) {
+      transport.emitInbound(
+        JSON.stringify({
+          version: "2",
+          event,
+          trace_id: `trace-${event}`,
+          emitted_at: Date.now(),
+          chat_id: "chat-1",
+          chat_type: "direct",
+          sender: { id: "user-1", type: "direct", nick_name: "User" },
+          payload: { message_id: "stream-fragment", fragments: [{ kind: "text", text: "part" }] },
+        }),
+      );
+    }
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "trace-inbound-complete",
+        emitted_at: 12345,
+        chat_id: "chat-1",
+        chat_type: "direct",
+        to: { id: "u", type: "direct" },
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
+        payload: {
+          message_id: "m-persist-inbound",
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello persisted" }] },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+          },
+        },
+      }),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    abortController.abort();
+    await run;
+
+    expect(store.claimMessageOnce).toHaveBeenCalledTimes(1);
+    expect(store.upsertConversationSummary).toHaveBeenCalledTimes(1);
+    expect(store.upsertConversationSummary).toHaveBeenCalledWith(expect.objectContaining({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "chat-1",
+      conversationType: "direct",
+      lastSeenAt: 12345,
+    }));
+    expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+    expect(store.claimMessageOnce).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      kind: "message",
+      direction: "inbound",
+      eventType: "message.send",
+      traceId: "trace-inbound-complete",
+      chatId: "chat-1",
+      messageId: "m-persist-inbound",
+      text: "hello persisted",
+      raw: expect.objectContaining({ event: "message.send" }),
+    });
+    expect(store.insertMessage).not.toHaveBeenCalled();
+  });
+
+  it("does not dispatch duplicate inbound messages already claimed in storage", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    const claimMessageOnce = vi.fn().mockReturnValueOnce(true).mockReturnValueOnce(false);
+    const runtime = {
+      agent: createTestMemoryAgent(),
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: {
+        startConnection: vi.fn(() => 1),
+        markConnectSent: vi.fn(),
+        markConnectionReady: vi.fn(),
+        finishConnection: vi.fn(),
+        claimMessageOnce,
+      },
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    const duplicateFrame = {
+      version: "2",
+      event: "message.send",
+      trace_id: "dup-trace",
+      emitted_at: Date.now(),
+      chat_id: "chat-1",
+      chat_type: "direct",
+      sender: { id: "user-1", type: "direct", nick_name: "User" },
+      payload: {
+        message_id: "duplicate-message",
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "hello" }] },
+          context: { mentions: [], reply: null },
+          streaming: {
+            status: "static",
+            sequence: 0,
+            mutation_policy: "sealed",
+            started_at: null,
+            completed_at: null,
+          },
+        },
+      },
+    };
+    transport.emitInbound(JSON.stringify(duplicateFrame));
+    transport.emitInbound(JSON.stringify({ ...duplicateFrame, trace_id: "dup-trace-2" }));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    abortController.abort();
+    await run;
+
+    expect(claimMessageOnce).toHaveBeenCalledTimes(2);
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispatches pending activation bootstrap through the normal direct inbound agent path after ready", async () => {
+    const capturedCtxs: Record<string, unknown>[] = [];
+    const resolveAgentRoute = vi.fn(() => ({
+      agentId: "default",
+      accountId: "default",
+      sessionKey: "session-from-route",
+    }));
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    const runtime = {
+      agent: createTestMemoryAgent(),
+      channel: {
+        routing: { resolveAgentRoute },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => {
+            capturedCtxs.push(ctx);
+            return ctx;
+          }),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) => {
+            const ctx = buildTestInboundContext(
+              params as Parameters<typeof buildTestInboundContext>[0],
+            );
+            capturedCtxs.push(ctx);
+            return ctx;
+          }),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 501),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      claimPendingActivationBootstrap: vi.fn(() => ({ conversationId: "conv-activation" })),
+      markActivationBootstrapSent: vi.fn(() => true),
+      releaseActivationBootstrapClaim: vi.fn(() => true),
+    };
+
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount({ token: "secret-token-value" }),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await completeHandshake(transport, "challenge-bootstrap-1");
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    abortController.abort();
+    await run;
+
+    expect(store.claimPendingActivationBootstrap).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+    });
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(
+      expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        kind: "message",
+        direction: "inbound",
+        eventType: "message.send",
+        chatId: "conv-activation",
+        messageId: expect.stringContaining("bootstrap"),
+      }),
+    );
+    expect(resolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({ peer: { kind: "direct", id: "conv-activation" } }),
+    );
+    expect(capturedCtxs).toHaveLength(1);
+    const ctx = capturedCtxs[0]!;
+    const bodyForAgent = String(ctx.BodyForAgent);
+    expect(ctx.From).toBe("openclaw-clawchat:conv-activation");
+    expect(ctx.OriginatingTo).toBe("openclaw-clawchat:conv-activation");
+    expect(ctx.ChatType).toBe("direct");
+    expect(bodyForAgent).toBe(EXPECTED_ACTIVATION_BOOTSTRAP_TEXT);
+    expect(bodyForAgent).not.toContain("secret-token-value");
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(store.markActivationBootstrapSent).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "conv-activation",
+    });
+    expect(dispatchReplyFromConfig.mock.invocationCallOrder[0]!).toBeLessThan(
+      store.markActivationBootstrapSent.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it("does not repeat an activation bootstrap across reconnect while the first dispatch is in flight", async () => {
+    let resolveDispatch: (value: unknown) => void = () => {};
+    const dispatchReplyFromConfig = vi.fn(
+      () =>
+        new Promise((resolve) => {
+          resolveDispatch = resolve;
+        }),
+    );
+    const runtime = {
+      agent: createTestMemoryAgent(),
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            accountId: "default",
+            sessionKey: "session-from-route",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 601),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      claimPendingActivationBootstrap: vi
+        .fn()
+        .mockReturnValueOnce({ conversationId: "conv-activation" })
+        .mockReturnValue(null),
+      markActivationBootstrapSent: vi.fn(() => true),
+      releaseActivationBootstrapClaim: vi.fn(() => true),
+    };
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount({
+        reconnect: {
+          initialDelay: 1,
+          maxDelay: 1,
+          jitterRatio: 0,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+      }),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await completeHandshake(transport, "challenge-bootstrap-first");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+    transport.close(1006, "network lost");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    await completeHandshake(transport, "challenge-bootstrap-reconnect");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(store.claimPendingActivationBootstrap).toHaveBeenCalledTimes(2);
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+    resolveDispatch({ counts: { final: 1, block: 0, tool: 0 }, queuedFinal: true });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    abortController.abort();
+    await run;
+
+    expect(store.markActivationBootstrapSent).toHaveBeenCalledTimes(1);
+    expect(store.markActivationBootstrapSent).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "conv-activation",
+    });
+  });
+
+  it("releases an activation bootstrap claim when agent submission fails", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockRejectedValue(new Error("dispatch failed"));
+    const runtime = {
+      agent: createTestMemoryAgent(),
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            accountId: "default",
+            sessionKey: "session-from-route",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 701),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      claimPendingActivationBootstrap: vi.fn(() => ({ conversationId: "conv-activation" })),
+      markActivationBootstrapSent: vi.fn(() => true),
+      releaseActivationBootstrapClaim: vi.fn(() => true),
+    };
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await completeHandshake(transport, "challenge-bootstrap-failure");
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    abortController.abort();
+    await run;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(store.markActivationBootstrapSent).not.toHaveBeenCalled();
+    expect(store.releaseActivationBootstrapClaim).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "conv-activation",
+    });
+  });
+
+  it("fetches inbound media via runtime.channel.media and populates MediaPath/MediaPaths", async () => {
+    const fetched: Array<{ url: string }> = [];
+    const saved: Array<{ ct: string | undefined }> = [];
+    let capturedCtx: Record<string, unknown> | undefined;
+    const buildContext = vi.fn((params: Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]) => {
+      capturedCtx = buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]);
+      return capturedCtx as ReturnType<PluginRuntime["channel"]["turn"]["buildContext"]>;
+    });
+    const resolveAgentRoute = vi.fn(() => ({
+      agentId: "u",
+      accountId: "default",
+      sessionKey: "s",
+    }));
+    const handlers = new Map<string, Function>();
+    registerClawChatPromptInjection({
+      on: vi.fn((name: string, handler: Function) => handlers.set(name, handler)),
+    });
+    let promptBuildResult: unknown;
+    const cfg = {
+      session: { store: "/tmp/sessions.json", dmScope: "main" },
+    } as unknown as OpenClawConfig;
+    const memoryRoot = tempMemoryRoot();
+    await writeClawChatMetadata(memoryRoot, { targetType: "owner", targetId: "owner" }, {
+      agent_id: "u",
+      owner_id: "owner-u",
+      nickname: "Hermes",
+      behavior: "Always be Hermes.",
+    });
+    await writeClawChatMetadata(memoryRoot, { targetType: "user", targetId: "user-1" }, {
+      id: "user-1",
+      nickname: "User",
+      avatar_url: "https://example.test/user.png",
+      bio: "Profile bio",
+      profile_type: "agent",
+    });
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      if (String(input) === "https://api.example.com/v1/users/user-1") {
+        return jsonEnvelope({
+          code: 0,
+          msg: "ok",
+          data: {
+            id: "user-1",
+            type: "agent",
+            nickname: "User",
+            avatar_url: "https://example.test/user.png",
+            bio: "Profile bio",
+          },
+        });
+      }
+      throw new Error(`unexpected fetch ${String(input)}`);
+    });
+    const store = {
+      startConnection: vi.fn(() => 201),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({ conversationId: "chat-1" })),
+      upsertConversationSummary: vi.fn(),
+    };
+
+    const runtime = {
+      agent: createTestMemoryAgent(memoryRoot),
+      channel: {
+        routing: {
+          resolveAgentRoute,
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
+            await opts.run();
+          }),
+          dispatchReplyFromConfig: vi.fn(async () => {
+            promptBuildResult = await handlers.get("before_prompt_build")?.({}, { sessionKey: "s" });
+          }),
+        },
+        turn: {
+          buildContext,
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(async ({ url }: { url: string }) => {
+            fetched.push({ url });
+            return { buffer: Buffer.from("x"), contentType: "image/png", fileName: "f.png" };
+          }),
+          saveMediaBuffer: vi.fn(async (_buf, ct?: string) => {
+            saved.push({ ct });
+            return { path: `/cache/${saved.length}.png`, contentType: "image/png" };
+          }),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const { MockTransport } = await import("./mock-transport.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg,
+      account: {
+        accountId: "default",
+        name: "openclaw-clawchat",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        ownerUserId: "owner-u",
+        replyMode: "static",
+        groupMode: "all",
+        groupCommandMode: "owner",
+        groups: {},
+        forwardThinking: true,
+        forwardToolCalls: false,
+        richInteractions: false,
+        allowFrom: [],
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0.3,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+        heartbeat: { interval: 25000, timeout: 10000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
+      },
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: () => {}, error: () => {} },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "tc",
+        emitted_at: Date.now(),
+        payload: { nonce: "n" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "ti",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
+        to: { id: "u", type: "direct" },
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
+        payload: {
+          message_id: "m-with-image",
+          message_mode: "normal",
+          message: {
+            body: {
+              fragments: [
+                { kind: "text", text: "see this:" },
+                { kind: "image", url: "https://cdn/a.png", mime: "image/png" },
+              ],
+            },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+          },
+        },
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(fetched).toEqual([{ url: "https://cdn/a.png" }]);
+    expect(capturedCtx?.MediaPath).toBe("/cache/1.png");
+    expect(capturedCtx?.MediaPaths).toEqual(["/cache/1.png"]);
+    expect(capturedCtx?.From).toBe("openclaw-clawchat:chat-1");
+    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:chat-1");
+    expect(capturedCtx?.ConversationLabel).toBe("chat-1");
+    expect(capturedCtx?.GroupSystemPrompt).toBeUndefined();
+    const directBuildContextArg = buildContext.mock.calls[0]?.[0] as
+      | Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]
+      | undefined;
+    expect(directBuildContextArg?.conversation.kind).toBe("direct");
+    expect(directBuildContextArg?.supplemental).toBeUndefined();
+    const directPrompt = (promptBuildResult as { appendSystemContext?: string }).appendSystemContext;
+    expect(directPrompt).toContain("## Current ClawChat Owner Metadata");
+    expect(directPrompt).toContain("behavior: Always be Hermes.");
+    expect(directPrompt).toContain("## Current ClawChat User Metadata");
+    expect(directPrompt).toContain("\nprofile_type: agent");
+    expect(directPrompt).toContain("nickname: User");
+    expect(directPrompt).toContain("avatar_url: https://example.test/user.png");
+    expect(directPrompt).toContain("bio: Profile bio");
+    expect(directPrompt).toContain("## Current ClawChat Message Metadata");
+    expect(directPrompt).toContain("chat_type: dm");
+    expect(directPrompt).toContain("sender_id: user-1");
+    expect(directPrompt).toContain("sender_profile_type: agent");
+    expect(directPrompt).toContain("sender_is_owner: false");
+    expect(directPrompt).not.toContain("sender_relation:");
+    expect(directPrompt).not.toContain("peer_id:");
+    expect(directPrompt).not.toContain("group_id:");
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://api.example.com/v1/users/user-1",
+      expect.objectContaining({ method: "GET" }),
+    );
+    expect(fetchSpy).not.toHaveBeenCalledWith("https://cdn/a.png", expect.anything());
+    expect(renderClawChatPromptInjectionForSession("s")).toBeUndefined();
+    expect(capturedCtx?.SenderId).toBe("user-1");
+    expect(resolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cfg: expect.objectContaining({
+          session: expect.objectContaining({
+            dmScope: "per-account-channel-peer",
+            store: "/tmp/sessions.json",
+          }),
+        }),
+        peer: { kind: "direct", id: "chat-1" },
+      }),
+    );
+    expect(cfg.session?.dmScope).toBe("main");
+    fetchSpy.mockRestore();
+  });
+
+  it("uses group chat_id as the canonical conversation identity", async () => {
+    vi.useFakeTimers();
+    let capturedCtx: Record<string, unknown> | undefined;
+    const buildContext = vi.fn((params: Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]) => {
+      capturedCtx = buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]);
+      return capturedCtx as ReturnType<PluginRuntime["channel"]["turn"]["buildContext"]>;
+    });
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    stageClawChatPromptInjection({ sessionKey: "s", prompt: "stale direct prompt" });
+    const store = {
+      startConnection: vi.fn(() => 202),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({ conversationId: "grp-1" })),
+      upsertConversationSummary: vi.fn(),
+    };
+
+    const runtime = {
+      agent: createTestMemoryAgent(),
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "u",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
+            await opts.run();
+          }),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext,
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as import("openclaw/plugin-sdk/core").OpenClawConfig,
+        account: {
+          accountId: "default",
+          name: "openclaw-clawchat",
+          enabled: true,
+          configured: true,
+          websocketUrl: "ws://t",
+          baseUrl: "https://api.example.com",
+          token: "tk",
+          userId: "u",
+          ownerUserId: "owner-u",
+          replyMode: "static",
+          groupMode: "all",
+          groupCommandMode: "owner",
+          groups: {},
+          forwardThinking: true,
+          forwardToolCalls: false,
+          richInteractions: false,
+          allowFrom: [],
+          stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+          reconnect: {
+            initialDelay: 1000,
+            maxDelay: 30000,
+            jitterRatio: 0.3,
+            maxRetries: Number.POSITIVE_INFINITY,
+          },
+          heartbeat: { interval: 25000, timeout: 10000 },
+          ack: { timeout: 10000, autoResendOnTimeout: false },
+        },
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: () => {}, error: () => {} },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+      await Promise.resolve();
+      transport.emitInbound(
+        JSON.stringify({
+          version: "2",
+          event: "connect.challenge",
+          trace_id: "tc",
+          emitted_at: Date.now(),
+          payload: { nonce: "n" },
+        }),
+      );
+      const connectFrame = transport.sent
+        .map((raw) => JSON.parse(raw))
+        .find((env) => env.event === "connect");
+      transport.emitInbound(
+        JSON.stringify({
+          version: "2",
+          event: "hello-ok",
+          trace_id: connectFrame.trace_id,
+          emitted_at: Date.now(),
+          payload: {},
+        }),
+      );
+      await vi.advanceTimersByTimeAsync(5);
+
+      transport.emitInbound(
+        JSON.stringify({
+          version: "2",
+          event: "message.send",
+          trace_id: "tg",
+          emitted_at: Date.now(),
+          chat_id: "grp-1",
+          chat_type: "group",
+          to: { id: "u", type: "group" },
+          sender: { id: "user-1", type: "direct", nick_name: "Alice" },
+          payload: {
+            message_id: "m-group",
+            message_mode: "normal",
+            message: {
+              body: {
+                fragments: [{ kind: "text", text: "hello group" }],
+              },
+              context: { mentions: [], reply: null },
+              streaming: {
+                status: "static",
+                sequence: 0,
+                mutation_policy: "sealed",
+                started_at: null,
+                completed_at: null,
+              },
+            },
+          },
+        }),
+      );
+      await Promise.resolve();
+      await vi.advanceTimersByTimeAsync(10000);
+      await vi.waitFor(() => expect(capturedCtx?.From).toBe("openclaw-clawchat:group:grp-1"));
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+
+    expect(capturedCtx?.From).toBe("openclaw-clawchat:group:grp-1");
+    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:group:grp-1");
+    expect(capturedCtx?.ConversationLabel).toBe("group:grp-1");
+    expect(capturedCtx?.SenderId).toBe("user-1");
+    expect(capturedCtx?.ChatType).toBe("group");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("## Current ClawChat Message Metadata");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("chat_type: group");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("## ClawChat Group Profile/Regulation");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("profile_id: grp-1");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("## Current ClawChat Message Metadata");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("## Current ClawChat Group Batch");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("chat_type: group");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("group_id: grp-1");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("was_mentioned:");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("mentioned_user_ids:");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("sender_id: user-1");
+    const groupBuildContextArg = buildContext.mock.calls[0]?.[0] as
+      | Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]
+      | undefined;
+    expect(groupBuildContextArg?.conversation.kind).toBe("group");
+    expect(groupBuildContextArg?.supplemental?.groupSystemPrompt).toContain("## Current ClawChat Message Metadata");
+    expect(renderClawChatPromptInjectionForSession("s")).toBeUndefined();
+    expect(dispatchReplyFromConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyOptions: expect.objectContaining({
+          sourceReplyDeliveryMode: "automatic",
+        }),
+      }),
+    );
+  });
+
+  it("coalesces eligible group messages after ten seconds of inactivity", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+      });
+
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-1",
+            senderId: "u1",
+            text: "first",
+            emittedAt: 1000,
+          }),
+        ),
+      );
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-2",
+            senderId: "u2",
+            senderType: "agent",
+            text: "second",
+            emittedAt: 2000,
+          }),
+        ),
+      );
+      await Promise.resolve();
+
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+      await vi.advanceTimersByTimeAsync(9999);
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+
+      await vi.advanceTimersByTimeAsync(1);
+
+      await vi.waitFor(() => expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1));
+      const ctx = dispatchReplyFromConfig.mock.calls[0]?.[0]?.ctx as Record<string, unknown>;
+      expect(ctx.RawBody).toContain("ClawChat group batch (2 messages, 10s idle, 30s max)");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u1\nsender_name: user-1\nsender_profile_type: user\nsender_is_owner: false\nmentions_current_agent: false\nmentioned_user_ids: -\ntext:\nfirst");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u2\nsender_name: user-2\nsender_profile_type: agent\nsender_is_owner: false\nmentions_current_agent: false\nmentioned_user_ids: -\ntext:\nsecond");
+      expect(ctx.RawBody).not.toContain("sender_relation");
+      expect(ctx.RawBody).not.toContain("[msg-");
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("## Current ClawChat Message Metadata"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("group_id: room-1"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("response_decision: Decide whether this group input needs a reply from you."));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("allowed_outputs: normal_reply OR exact_empty_response"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining('exact_empty_response: ""'));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining('no_reply_protocol: If you choose not to reply, return exactly "" and nothing else.'));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("silent_response:"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("sender_id: u"));
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("dispatches owner group slash commands without group batching", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount({ groupCommandMode: "owner", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+      });
+
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "cmd-owner",
+            senderId: "owner-u",
+            text: "/reset",
+          }),
+        ),
+      );
+
+      await vi.waitFor(() => {
+        expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+      });
+      const ctx = dispatchReplyFromConfig.mock.calls[0]?.[0]?.ctx as Record<string, unknown>;
+      expect(ctx.RawBody).toBe("/reset");
+      expect(ctx.CommandBody).toBe("/reset");
+      expect(ctx.RawBody).not.toContain("ClawChat group batch");
+
+      await vi.advanceTimersByTimeAsync(10000);
+      expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("drops non-owner group slash commands in owner command mode", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount({ groupCommandMode: "owner", ownerUserId: "owner-u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+      });
+
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "cmd-non-owner",
+            senderId: "user-1",
+            text: "/reset",
+          }),
+        ),
+      );
+      await Promise.resolve();
+      await vi.advanceTimersByTimeAsync(10000);
+
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("uses envelope sender identity in coalesced group transcripts when memory is not injected", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      const store = {
+        startConnection: vi.fn(() => 901),
+        markConnectSent: vi.fn(),
+        markConnectionReady: vi.fn(),
+        finishConnection: vi.fn(),
+        getCachedConversation: vi.fn(() => ({ conversationId: "room-1" })),
+        upsertConversationSummary: vi.fn(),
+        upsertConversationDetails: vi.fn(),
+      };
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-1",
+            senderId: "usr_colin",
+            text: "first",
+            emittedAt: 1000,
+          }),
+        ),
+      );
+      await Promise.resolve();
+
+      await vi.advanceTimersByTimeAsync(10000);
+
+      await vi.waitFor(() => expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1));
+      const ctx = dispatchReplyFromConfig.mock.calls[0]?.[0]?.ctx as Record<string, unknown>;
+      expect(ctx.RawBody).toContain("[message]\nsender_id: usr_colin\nsender_name: usr_colin\nsender_profile_type: user\nsender_is_owner: false\nmentions_current_agent: false\nmentioned_user_ids: -\ntext:\nfirst");
+      expect(ctx.RawBody).not.toContain("sender_name: ColinShen");
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("dispatches group messages that mention the configured account immediately", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount({ groupMode: "all", userId: "u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+      });
+
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-mention-self",
+            senderId: "u1",
+            text: "urgent",
+            mentions: ["u"],
+          }),
+        ),
+      );
+
+      await vi.advanceTimersByTimeAsync(1);
+      await vi.waitFor(() => expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1));
+      await vi.advanceTimersByTimeAsync(9999);
+      expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+      const ctx = dispatchReplyFromConfig.mock.calls[0]?.[0]?.ctx as Record<string, unknown>;
+      expect(ctx.RawBody).toContain("ClawChat group batch (1 message, 10s idle, 30s max)");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u1\nsender_name: user-1\nsender_profile_type: user\nsender_is_owner: false\nmentions_current_agent: true\nmentioned_user_ids: u\ntext:\nurgent");
+      expect(ctx.WasMentioned).toBe(true);
+      expect(ctx.MentionedUserIds).toEqual(["u"]);
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("## Current ClawChat Message Metadata"));
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("flushes pending group batch immediately when a later message mentions the configured account", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount({ groupMode: "all", userId: "u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+      });
+
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-quiet",
+            senderId: "u1",
+            text: "context",
+            emittedAt: 1000,
+          }),
+        ),
+      );
+      await vi.advanceTimersByTimeAsync(1000);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-mention-self",
+            senderId: "u2",
+            text: "urgent",
+            mentions: ["u"],
+            emittedAt: 2000,
+          }),
+        ),
+      );
+
+      await vi.advanceTimersByTimeAsync(1);
+      await vi.waitFor(() => expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1));
+      const ctx = dispatchReplyFromConfig.mock.calls[0]?.[0]?.ctx as Record<string, unknown>;
+      expect(ctx.RawBody).toContain("ClawChat group batch (2 messages, 10s idle, 30s max)");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u1\nsender_name: user-1\nsender_profile_type: user\nsender_is_owner: false\nmentions_current_agent: false\nmentioned_user_ids: -\ntext:\ncontext");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u2\nsender_name: user-2\nsender_profile_type: user\nsender_is_owner: false\nmentions_current_agent: true\nmentioned_user_ids: u\ntext:\nurgent");
+      expect(ctx.RawBody).not.toContain("[msg-");
+      expect(ctx.WasMentioned).toBe(true);
+      expect(ctx.MentionedUserIds).toEqual(["u"]);
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("## Current ClawChat Message Metadata"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("was_mentioned:"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("mentioned_user_ids:"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("response_decision: Decide whether this group input needs a reply from you."));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("allowed_outputs: normal_reply OR exact_empty_response"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining('exact_empty_response: ""'));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("silent_response:"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("\nempty_response:"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("sender_id: u2"));
+
+      await vi.advanceTimersByTimeAsync(30000);
+      expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 
-    await vi.advanceTimersByTimeAsync(5000);
-    expect(logs).toContain(
-      "clawchat.ws event=reconnect_backoff_reset account_id=default attempt=2 reconnect_count=0 state=ready action=reset stable_ms=5000",
-    );
+  it("exposes mentioned user ids for groupMode all messages that mention others", async () => {
+    vi.useFakeTimers();
+    try {
+      const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+        counts: { final: 1, block: 0, tool: 0 },
+        queuedFinal: true,
+      });
+      const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+      setOpenclawClawlingRuntime(runtime);
+      const transport = new MockTransport();
+      const abortController = new AbortController();
+      const startPromise = startOpenclawClawlingGateway({
+        cfg: {} as OpenClawConfig,
+        account: baseAccount({ groupMode: "all", userId: "u" }),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ accountId: "default" })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+      });
 
-    abortController.abort();
-    await run;
-    vi.useRealTimers();
+      await completeHandshake(transport);
+      transport.emitInbound(
+        JSON.stringify(
+          inboundMessageEnvelope({
+            chatId: "room-1",
+            chatType: "group",
+            messageId: "msg-mention-other",
+            senderId: "u1",
+            text: "heads up",
+            mentions: ["other-user"],
+          }),
+        ),
+      );
+
+      await vi.advanceTimersByTimeAsync(9999);
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+      await vi.advanceTimersByTimeAsync(1);
+
+      await vi.waitFor(() => expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1));
+      const ctx = dispatchReplyFromConfig.mock.calls[0]?.[0]?.ctx as Record<string, unknown>;
+      expect(ctx.WasMentioned).toBe(false);
+      expect(ctx.MentionedUserIds).toEqual(["other-user"]);
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("## Current ClawChat Message Metadata"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("mentioned_user_ids: other-user"));
+      expect(ctx.RawBody).toContain("mentions_current_agent: false\nmentioned_user_ids: other-user");
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
   });
-});
 
-describe("openclaw-clawchat runtime media ingest", () => {
-  it("fetches inbound media via runtime.channel.media and populates MediaPath/MediaPaths", async () => {
-    const fetched: Array<{ url: string }> = [];
-    const saved: Array<{ ct: string | undefined }> = [];
-    let capturedCtx: Record<string, unknown> | undefined;
-    const finalizeInboundContext = vi.fn((ctx: Record<string, unknown>) => {
-      capturedCtx = ctx;
-      return ctx;
+  it("does not coalesce direct messages or change direct prompt injection", async () => {
+    const handlers = new Map<string, Function>();
+    registerClawChatPromptInjection({
+      on: vi.fn((name: string, handler: Function) => handlers.set(name, handler)),
     });
-    const resolveAgentRoute = vi.fn(() => ({
-      agentId: "u",
-      accountId: "default",
-      sessionKey: "s",
-    }));
-    const cfg = {
-      session: { store: "/tmp/sessions.json", dmScope: "main" },
-    } as unknown as OpenClawConfig;
+    let promptBuildResult: unknown;
+    const dispatchReplyFromConfig = vi.fn(async () => {
+      promptBuildResult = await handlers.get("before_prompt_build")?.({}, {
+        sessionKey: "session-from-route",
+      });
+      return { counts: { final: 1, block: 0, tool: 0 }, queuedFinal: true };
+    });
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+    });
+
+    await completeHandshake(transport);
+    transport.emitInbound(
+      JSON.stringify(
+        inboundMessageEnvelope({
+          chatId: "chat-1",
+          chatType: "direct",
+          messageId: "dm-1",
+          senderId: "u1",
+          text: "hello",
+        }),
+      ),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    abortController.abort();
+    await startPromise;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(promptBuildResult).toEqual({
+      appendSystemContext: expect.stringContaining("## Current ClawChat Message Metadata"),
+    });
+  });
 
+  it("dispatches completed message.done frames to the OpenClaw agent path", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
     const runtime = {
+      agent: createTestMemoryAgent(),
       channel: {
         routing: {
-          resolveAgentRoute,
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            accountId: "default",
+            sessionKey: "s",
+          })),
         },
         session: {
           resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
@@ -620,7 +4226,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
         reply: {
           formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
           resolveEnvelopeFormatOptions: vi.fn(() => ({})),
-          finalizeInboundContext,
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
           resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
           createReplyDispatcherWithTyping: vi.fn(() => ({
             dispatcher: {},
@@ -628,150 +4234,102 @@ describe("openclaw-clawchat runtime media ingest", () => {
             markDispatchIdle: vi.fn(),
             markRunComplete: vi.fn(),
           })),
-          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
-            await opts.run();
-          }),
-          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+          withReplyDispatcher: vi.fn(
+            async (opts: { run: () => Promise<unknown>; onSettled?: () => void | Promise<void> }) => {
+              try {
+                return await opts.run();
+              } finally {
+                await opts.onSettled?.();
+              }
+            },
+          ),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
         },
         media: {
-          fetchRemoteMedia: vi.fn(async ({ url }: { url: string }) => {
-            fetched.push({ url });
-            return { buffer: Buffer.from("x"), contentType: "image/png", fileName: "f.png" };
-          }),
-          saveMediaBuffer: vi.fn(async (_buf, ct?: string) => {
-            saved.push({ ct });
-            return { path: `/cache/${saved.length}.png`, contentType: "image/png" };
-          }),
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
           loadWebMedia: vi.fn(),
         },
       },
-    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
-
+    } as unknown as PluginRuntime;
     setOpenclawClawlingRuntime(runtime);
-
-    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
-    const { MockTransport } = await import("@newbase-clawchat/sdk");
     const transport = new MockTransport();
     const abortController = new AbortController();
 
-    const startPromise = startOpenclawClawlingGateway({
-      cfg,
-      account: {
-        accountId: "default",
-        name: "openclaw-clawchat",
-        enabled: true,
-        configured: true,
-        websocketUrl: "ws://t",
-        baseUrl: "https://api.example.com",
-        token: "tk",
-        userId: "u",
-        replyMode: "static",
-        forwardThinking: true,
-        forwardToolCalls: false,
-        allowFrom: [],
-        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
-        reconnect: {
-          initialDelay: 1000,
-          maxDelay: 30000,
-          jitterRatio: 0.3,
-          maxRetries: Number.POSITIVE_INFINITY,
-        },
-        heartbeat: { interval: 25000, timeout: 10000 },
-        ack: { timeout: 10000, autoResendOnTimeout: false },
-      },
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
       abortSignal: abortController.signal,
       setStatus: vi.fn(),
-      getStatus: vi.fn(() => ({ accountId: "default" })),
-      log: { info: () => {}, error: () => {} },
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
       transport,
     });
 
-    await new Promise((r) => setTimeout(r, 0));
+    await Promise.resolve();
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "connect.challenge",
-        trace_id: "tc",
+        trace_id: "challenge",
         emitted_at: Date.now(),
-        payload: { nonce: "n" },
+        payload: { nonce: "nonce" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "th",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
     );
-    await new Promise((r) => setTimeout(r, 5));
-
+    await Promise.resolve();
     transport.emitInbound(
       JSON.stringify({
         version: "2",
-        event: "message.send",
-        trace_id: "ti",
+        event: "message.done",
+        trace_id: "done-1",
         emitted_at: Date.now(),
         chat_id: "chat-1",
         chat_type: "direct",
-        to: { id: "u", type: "direct" },
         sender: { id: "user-1", type: "direct", nick_name: "User" },
         payload: {
-          message_id: "m-with-image",
-          message_mode: "normal",
-          message: {
-            body: {
-              fragments: [
-                { kind: "text", text: "see this:" },
-                { kind: "image", url: "https://cdn/a.png", mime: "image/png" },
-              ],
-            },
-            context: { mentions: [], reply: null },
-            streaming: {
-              status: "static",
-              sequence: 0,
-              mutation_policy: "sealed",
-              started_at: null,
-              completed_at: null,
-            },
+          message_id: "stream-1",
+          fragments: [{ kind: "text", text: "completed stream" }],
+          streaming: {
+            status: "done",
+            sequence: 1,
+            mutation_policy: "append_text_only",
+            started_at: null,
+            completed_at: Date.now(),
           },
         },
       }),
     );
-    await new Promise((r) => setTimeout(r, 30));
+    await new Promise((resolve) => setTimeout(resolve, 10));
     abortController.abort();
-    await startPromise;
+    await run;
 
-    expect(fetched).toEqual([{ url: "https://cdn/a.png" }]);
-    expect(capturedCtx?.MediaPath).toBe("/cache/1.png");
-    expect(capturedCtx?.MediaPaths).toEqual(["/cache/1.png"]);
-    expect(capturedCtx?.From).toBe("openclaw-clawchat:chat-1");
-    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:chat-1");
-    expect(capturedCtx?.ConversationLabel).toBe("chat-1");
-    expect(capturedCtx?.SenderId).toBe("user-1");
-    expect(resolveAgentRoute).toHaveBeenCalledWith(
-      expect.objectContaining({
-        cfg: expect.objectContaining({
-          session: expect.objectContaining({
-            dmScope: "per-account-channel-peer",
-            store: "/tmp/sessions.json",
-          }),
-        }),
-        peer: { kind: "direct", id: "chat-1" },
-      }),
-    );
-    expect(cfg.session?.dmScope).toBe("main");
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(renderClawChatPromptInjectionForSession("s")).toBeUndefined();
   });
+});
 
-  it("uses group chat_id as the canonical conversation identity", async () => {
-    let capturedCtx: Record<string, unknown> | undefined;
-    const finalizeInboundContext = vi.fn((ctx: Record<string, unknown>) => {
-      capturedCtx = ctx;
-      return ctx;
-    });
-
+describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
+  it("clears staged direct prompt when dispatcher setup fails before dispatch", async () => {
+    const logError = vi.fn();
     const runtime = {
+      agent: createTestMemoryAgent(),
       channel: {
         routing: {
           resolveAgentRoute: vi.fn(() => ({
@@ -787,18 +4345,18 @@ describe("openclaw-clawchat runtime media ingest", () => {
         reply: {
           formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
           resolveEnvelopeFormatOptions: vi.fn(() => ({})),
-          finalizeInboundContext,
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
           resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
-          createReplyDispatcherWithTyping: vi.fn(() => ({
-            dispatcher: {},
-            replyOptions: {},
-            markDispatchIdle: vi.fn(),
-            markRunComplete: vi.fn(),
-          })),
-          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
-            await opts.run();
+          createReplyDispatcherWithTyping: vi.fn(() => {
+            throw new Error("dispatcher setup failed");
           }),
-          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+          withReplyDispatcher: vi.fn(),
+          dispatchReplyFromConfig: vi.fn(),
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
         },
         media: {
           fetchRemoteMedia: vi.fn(),
@@ -806,44 +4364,19 @@ describe("openclaw-clawchat runtime media ingest", () => {
           loadWebMedia: vi.fn(),
         },
       },
-    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    } as unknown as PluginRuntime;
 
     setOpenclawClawlingRuntime(runtime);
 
-    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
     const transport = new MockTransport();
     const abortController = new AbortController();
-
     const startPromise = startOpenclawClawlingGateway({
-      cfg: {} as import("openclaw/plugin-sdk/core").OpenClawConfig,
-      account: {
-        accountId: "default",
-        name: "openclaw-clawchat",
-        enabled: true,
-        configured: true,
-        websocketUrl: "ws://t",
-        baseUrl: "https://api.example.com",
-        token: "tk",
-        userId: "u",
-        replyMode: "static",
-        groupMode: "all",
-        forwardThinking: true,
-        forwardToolCalls: false,
-        allowFrom: [],
-        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
-        reconnect: {
-          initialDelay: 1000,
-          maxDelay: 30000,
-          jitterRatio: 0.3,
-          maxRetries: Number.POSITIVE_INFINITY,
-        },
-        heartbeat: { interval: 25000, timeout: 10000 },
-        ack: { timeout: 10000, autoResendOnTimeout: false },
-      },
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
       abortSignal: abortController.signal,
       setStatus: vi.fn(),
       getStatus: vi.fn(() => ({ accountId: "default" })),
-      log: { info: () => {}, error: () => {} },
+      log: { info: vi.fn(), error: logError },
       transport,
     });
 
@@ -857,11 +4390,14 @@ describe("openclaw-clawchat runtime media ingest", () => {
         payload: { nonce: "n" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "th",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
@@ -872,18 +4408,18 @@ describe("openclaw-clawchat runtime media ingest", () => {
       JSON.stringify({
         version: "2",
         event: "message.send",
-        trace_id: "tg",
+        trace_id: "tm",
         emitted_at: Date.now(),
-        chat_id: "grp-1",
-        chat_type: "group",
-        to: { id: "u", type: "group" },
-        sender: { id: "user-1", type: "direct", nick_name: "Alice" },
+        chat_id: "chat-1",
+        chat_type: "direct",
+        to: { id: "u", type: "direct" },
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
         payload: {
-          message_id: "m-group",
+          message_id: "m-setup-fail",
           message_mode: "normal",
           message: {
             body: {
-              fragments: [{ kind: "text", text: "hello group" }],
+              fragments: [{ kind: "text", text: "hello" }],
             },
             context: { mentions: [], reply: null },
             streaming: {
@@ -897,19 +4433,18 @@ describe("openclaw-clawchat runtime media ingest", () => {
         },
       }),
     );
+
     await new Promise((r) => setTimeout(r, 30));
     abortController.abort();
     await startPromise;
 
-    expect(capturedCtx?.From).toBe("openclaw-clawchat:group:grp-1");
-    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:group:grp-1");
-    expect(capturedCtx?.ConversationLabel).toBe("group:grp-1");
-    expect(capturedCtx?.SenderId).toBe("user-1");
-    expect(capturedCtx?.ChatType).toBe("group");
+    expect(runtime.channel.reply.dispatchReplyFromConfig).not.toHaveBeenCalled();
+    expect(renderClawChatPromptInjectionForSession("s")).toBeUndefined();
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("openclaw-clawchat message handler error"),
+    );
   });
-});
 
-describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
   it("marks dispatch idle when reply dispatch fails", async () => {
     const markDispatchIdle = vi.fn();
     const withReplyDispatcher = vi.fn(
@@ -925,6 +4460,7 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
     const logError = vi.fn();
 
     const runtime = {
+      agent: createTestMemoryAgent(),
       channel: {
         routing: {
           resolveAgentRoute: vi.fn(() => ({
@@ -950,6 +4486,11 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
           withReplyDispatcher,
           dispatchReplyFromConfig,
         },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
         media: {
           fetchRemoteMedia: vi.fn(),
           saveMediaBuffer: vi.fn(),
@@ -1006,11 +4547,14 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
         payload: { nonce: "n" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "th",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
@@ -1115,11 +4659,14 @@ describe("openclaw-clawchat runtime connect flow", () => {
         payload: { nonce: "n1" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "t2",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),