@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/runtime.test.ts

@@ -0,0 +1,4719 @@
+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 { 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,
+  getOpenclawClawlingClient,
+} 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> = {},
+): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: "default",
+    name: "clawchat-plugin-openclaw",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://t",
+    baseUrl: "https://api.example.com",
+    token: "tk",
+    agentId: "agt-1",
+    userId: "u",
+    ownerUserId: "owner-u",
+    groupMode: "all",
+    groupCommandMode: "owner",
+    groups: {},
+    forwardThinking: true,
+    forwardToolCalls: false,
+    richInteractions: false,
+    allowFrom: [],
+    reconnect: {
+      initialDelay: 1000,
+      maxDelay: 30000,
+      jitterRatio: 0.3,
+      maxRetries: Number.POSITIVE_INFINITY,
+    },
+    heartbeat: { interval: 25000, timeout: 10000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+    ...overrides,
+  };
+}
+
+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(), "clawchat-plugin-openclaw-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: "owner-u",
+                role: "owner",
+                joined_at: "2026-05-24T01:00:00.000Z",
+              },
+              {
+                conversation_id: groupId,
+                user_id: "u",
+                role: "member",
+                joined_at: "2026-05-24T01:00:30.000Z",
+              },
+              {
+                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 agent behavior.",
+            updated_at: "2026-05-24T01:03:00.000Z",
+          },
+        },
+      });
+    }
+    return new Response("unexpected test URL", { status: 500 });
+  });
+}
+
+describe("clawchat-plugin-openclaw runtime memory metadata refresh", () => {
+  it("dispatches inbound turns when OpenClaw exposes channel.inbound without channel.turn", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const fetchMock = mockMetadataFetches();
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig, memoryRoot) as PluginRuntime & {
+      channel: PluginRuntime["channel"] & {
+        inbound?: {
+          buildContext: (params: Parameters<typeof buildTestInboundContext>[0]) => ReturnType<typeof buildTestInboundContext>;
+        };
+        turn?: unknown;
+      };
+    };
+    const buildContext = vi.fn((params: Parameters<typeof buildTestInboundContext>[0]) =>
+      buildTestInboundContext(params),
+    );
+    runtime.channel.inbound = { buildContext };
+    delete runtime.channel.turn;
+    const store = {
+      startConnection: vi.fn(() => 500),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: 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-inbound-runtime");
+      transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+        chatId: "dm-inbound-runtime",
+        chatType: "direct",
+        messageId: "msg-inbound-runtime",
+        senderId: "user-inbound",
+        text: "hello",
+      })));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(buildContext).toHaveBeenCalledTimes(1);
+      expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  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",
+        agent_owner_id: "owner-u",
+        agent_owner_nickname: "User owner-u",
+        agent_behavior: "Use current agent behavior.",
+      });
+      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(),
+      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",
+      agent_owner_id: "owner-u",
+      agent_owner_nickname: "Owner",
+      agent_behavior: "Use agent 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(),
+      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("## ClawChat Agent Owner Metadata");
+      expect(directPrompt).not.toContain("## ClawChat Peer Profile");
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("writes a development LLM context snapshot for an inbound direct prompt", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const debugRoot = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-llm-context-runtime-"));
+    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(() => ({ conversationId: "dm-debug" })),
+      claimMessageOnce: vi.fn(() => true),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    vi.stubEnv("CLAWCHAT_LLM_CONTEXT_DEBUG", "1");
+    vi.stubEnv("CLAWCHAT_LLM_CONTEXT_SNAPSHOT_DIR", debugRoot);
+    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-llm-context-debug");
+      transport.emitInbound(JSON.stringify(inboundMessageEnvelope({
+        chatId: "dm-debug",
+        chatType: "direct",
+        messageId: "msg-debug",
+        senderId: "owner-u",
+        text: "hello debug snapshot",
+      })));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const runsDir = path.join(debugRoot, "openclaw", "runs");
+      const files = fs.readdirSync(runsDir).filter((name) => name.endsWith(".json"));
+      expect(files).toHaveLength(1);
+      const snapshot = JSON.parse(fs.readFileSync(path.join(runsDir, files[0]!), "utf8"));
+      expect(snapshot.source).toBe("openclaw");
+      expect(snapshot.visibility).toBe("injected_only");
+      expect(snapshot.input.injectedPrompt).toContain("ClawChat Metadata Glossary");
+      expect(snapshot.input.eventText).toBe("hello debug snapshot");
+      expect(snapshot.trace.sessionKey).toBe("session-from-route");
+
+      abortController.abort();
+      await run;
+    } finally {
+      vi.unstubAllEnvs();
+      fetchMock.mockRestore();
+      fs.rmSync(debugRoot, { recursive: true, force: true });
+    }
+  });
+
+  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(),
+      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 ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "owner-u" });
+      const selfFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "u" });
+      const participantFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "participant-1" });
+      const participantAgentFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: "participant-agent" });
+      expect(groupFile.metadata).toMatchObject({
+        group_id: "grp-memory",
+        group_title: "Room grp-memory",
+        group_description: "Description grp-memory",
+        participant_ids: "owner-u,u,participant-1,participant-agent",
+      });
+      expect(ownerFile.exists).toBe(false);
+      expect(selfFile.exists).toBe(false);
+      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(),
+      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({
+        group_id: "grp-cached",
+        group_title: "Room grp-cached",
+        participant_ids: "owner-u,u,participant-1,participant-agent",
+      });
+      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",
+        agent_behavior: "Use current agent behavior.",
+      });
+      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(),
+    };
+    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({
+        group_id: `grp-${_name}`,
+        group_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("clawchat-plugin-openclaw runtime helpers", () => {
+  it("maps local client states to channel status shape", () => {
+    expect(mapClawlingStateToStatus("connected")).toMatchObject({
+      connected: true,
+      running: true,
+    });
+    expect(mapClawlingStateToStatus("reconnecting")).toMatchObject({
+      connected: false,
+      running: true,
+    });
+    expect(mapClawlingStateToStatus("disconnected")).toMatchObject({
+      connected: false,
+      running: false,
+    });
+    expect(mapClawlingStateToStatus("connecting")).toMatchObject({
+      connected: false,
+      running: true,
+    });
+  });
+
+  it("classifies AuthError as fatal/no-retry", () => {
+    const c = classifyClawlingClientError(new AuthError("bad-token"));
+    expect(c.kind).toBe("auth");
+    expect(c.retry).toBe(false);
+  });
+
+  it("classifies generic errors as unknown", () => {
+    const c = classifyClawlingClientError(new Error("huh"));
+    expect(c.kind).toBe("unknown");
+    expect(c.retry).toBe(false);
+  });
+
+  it("runtime store round-trips", () => {
+    const rt = { mocked: true } as unknown as PluginRuntime;
+    setOpenclawClawlingRuntime(rt);
+    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();
+    const account = baseAccount();
+    const abortController = new AbortController();
+
+    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");
+    expect(logs).toContain(
+      "clawchat.ws event=connect_start account_id=default attempt=1 reconnect_count=0 state=connecting action=connect url=ws://t queue_size=0",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=challenge_received account_id=default attempt=1 reconnect_count=0 state=handshaking action=send_connect challenge_trace_id=challenge-1 has_nonce=true",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=connect_sent account_id=default attempt=1 reconnect_count=0 state=handshaking action=await_hello trace_id=" +
+        connectFrame.trace_id +
+        " device_id=u",
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-fail",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: { reason: "authentication failed" },
+      }),
+    );
+
+    await run;
+
+    expect(logs).toContain(
+      "clawchat.ws event=auth_failed account_id=default attempt=1 reconnect_count=0 state=auth_failed action=stop_reconnect trace_id=" +
+        connectFrame.trace_id +
+        " reason=authentication failed",
+    );
+    expect(logs.some((line) => line.includes("event=handshake_ok"))).toBe(false);
+    expect(logs.some((line) => line.includes("event=reconnect_scheduled"))).toBe(false);
+  });
+
+  it("logs canonical websocket lifecycle for the first successful connect", 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();
+
+    expect(logs).toContain(
+      "clawchat.ws event=connect_start account_id=default attempt=1 reconnect_count=0 state=connecting action=connect url=ws://t queue_size=0",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=challenge_received account_id=default attempt=1 reconnect_count=0 state=handshaking action=send_connect challenge_trace_id=challenge-1 has_nonce=true",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=connect_sent account_id=default attempt=1 reconnect_count=0 state=handshaking action=await_hello trace_id=" +
+        connectFrame.trace_id +
+        " device_id=u",
+    );
+    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("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({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ 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-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();
+
+    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("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({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ 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-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: { device_id: "device-resolved", delivery_mode: "device_replay" },
+      }),
+    );
+    await Promise.resolve();
+
+    abortController.abort();
+    await run;
+
+    expect(store.markConnectionReady).toHaveBeenCalledWith(
+      111,
+      expect.objectContaining({
+        resolvedDeviceId: "device-resolved",
+        deliveryMode: "device_replay",
+      }),
+    );
+  });
+
+  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(),
+    };
+    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: "chat.metadata.invalidated",
+        trace_id: "meta-refresh",
+        emitted_at: Date.now(),
+        chat_id: "group-1",
+        chat_type: "group",
+        payload: { scope: ["unknown"], version: 7 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 30));
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/group-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+      await expect(readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "group-1" }))
+        .resolves.toMatchObject({ metadata: expect.objectContaining({ group_title: "Room group-1" }) });
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  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(),
+    };
+    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-stale");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-missing-chat",
+        emitted_at: Date.now(),
+        payload: { version: 10 },
+      }));
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-stale",
+        emitted_at: Date.now(),
+        chat_id: "group-stale",
+        payload: { version: 9 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 30));
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/group-stale",
+        expect.objectContaining({ method: "GET" }),
+      );
+      await expect(readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "group-stale" }))
+        .resolves.toMatchObject({ metadata: expect.objectContaining({ group_title: "Room 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 memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    await writeClawChatMetadata(memoryRoot, { targetType: "group", targetId: "group-missing" }, {
+      group_id: "group-missing",
+      group_title: "Stale",
+    });
+    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: 4001, 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(),
+    };
+    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: "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));
+
+      await expect(readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "group-no-version" }))
+        .resolves.toMatchObject({ metadata: expect.objectContaining({ group_title: "Room group-no-version" }) });
+      await expect(readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "group-missing" }))
+        .resolves.toMatchObject({ exists: false });
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  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(),
+    };
+    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-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));
+
+      const groupFile = await readClawChatMemoryFile(memoryRoot, {
+        targetType: "group",
+        targetId: "group-clear-description",
+      });
+      expect(groupFile.metadata).toMatchObject({ group_id: "group-clear-description" });
+      expect(groupFile.metadata).not.toHaveProperty("group_description");
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("refreshes behavior invalidations from the agent endpoint and stores agent_behavior in owner.md", async () => {
+    const memoryRoot = tempMemoryRoot();
+    const runtime = buildNoDispatchRuntime(vi.fn().mockResolvedValue(undefined), memoryRoot);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = String(input);
+      if (url.endsWith("/v1/agents/agt-1")) {
+        return jsonEnvelope({
+          code: 0,
+          msg: "ok",
+          data: {
+            agent: {
+              id: "agent-row",
+              user_id: "u",
+              owner_id: "owner-u",
+              type: "agent",
+              nickname: "Agent Runtime",
+              avatar_url: "https://example.test/agent.png",
+              bio: "Agent runtime bio",
+              behavior: "Use updated behavior.",
+            },
+          },
+        });
+      }
+      if (url.endsWith("/v1/users/owner-u")) {
+        return jsonEnvelope({
+          code: 0,
+          msg: "ok",
+          data: {
+            id: "owner-u",
+            nickname: "Owner",
+            avatar_url: "https://example.test/owner.png",
+            bio: "Owner bio",
+          },
+        });
+      }
+      return new Response("unexpected test URL", { status: 500 });
+    });
+    const store = {
+      startConnection: vi.fn(() => 127),
+      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-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",
+        agent_owner_id: "owner-u",
+        agent_nickname: "Agent Runtime",
+        agent_avatar_url: "https://example.test/agent.png",
+        agent_bio: "Agent runtime bio",
+        agent_owner_nickname: "Owner",
+        agent_owner_avatar_url: "https://example.test/owner.png",
+        agent_owner_bio: "Owner bio",
+        agent_behavior: "Use updated behavior.",
+      });
+      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").mockImplementation(async (input) => {
+      const url = String(input);
+      if (url.endsWith("/v1/agents/agt-1")) {
+        return jsonEnvelope({
+          code: 0,
+          msg: "ok",
+          data: {
+            agent: {
+              user_id: "u",
+              owner_id: "owner-u",
+              type: "agent",
+              nickname: "Agent Runtime",
+              behavior: null,
+            },
+          },
+        });
+      }
+      if (url.endsWith("/v1/users/owner-u")) {
+        return jsonEnvelope({
+          code: 0,
+          msg: "ok",
+          data: {
+            id: "owner-u",
+            nickname: "Owner",
+          },
+        });
+      }
+      return new Response("unexpected test URL", { status: 500 });
+    });
+    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",
+        agent_owner_id: "owner-u",
+        agent_nickname: "Agent Runtime",
+        agent_owner_nickname: "Owner",
+      });
+      expect(ownerFile.metadata).not.toHaveProperty("agent_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 store = {
+      startConnection: vi.fn(() => 128),
+      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-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",
+      });
+      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(),
+    };
+    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("## ClawChat Peer Profile");
+      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("sender_is_agent_owner:");
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("uses dm plus sender_is_agent_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(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    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-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("sender_is_agent_owner:");
+    expect(directPrompt).toContain("sender_is_agent_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(),
+    };
+    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);
+      const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: "grp-profile" });
+      expect(groupFile.metadata).toMatchObject({
+        group_id: "grp-profile",
+        group_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(),
+    };
+    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(logs.some((line) => line.includes("metadata refresh failed"))).toBe(true);
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("does not refresh SQLite conversation state after hello-ok or write 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 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,
+      })),
+      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(requestedIds).toEqual([]);
+      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: vi.fn(), error: vi.fn() },
+      transport,
+      store: transportStore,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-transport",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    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: transportConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+    transport.emitError(new Error("socket down"));
+    await Promise.resolve();
+    abortController.abort();
+    await transportRun;
+
+    expect(transportStore.finishConnection).toHaveBeenCalledWith(
+      301,
+      expect.objectContaining({ state: "transport_error", error: "socket down" }),
+    );
+  });
+
+  it("logs handshake_ok with the connect trace", 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();
+
+    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("logs JSON ping and pong as protocol control", 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.sent.length = 0;
+
+    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",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=reconnect_scheduled account_id=default attempt=1 reconnect_count=1 state=reconnecting action=wait delay_ms=1000 max_delay_ms=30000 reason=connection_lost",
+    );
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await Promise.resolve();
+    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();
+
+    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("clawchat-plugin-openclaw 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(),
+    };
+    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", "message.done"]) {
+      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.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("clawchat-plugin-openclaw:conv-activation");
+    expect(ctx.OriginatingTo).toBe("clawchat-plugin-openclaw: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",
+      agent_owner_id: "owner-u",
+      agent_owner_nickname: "Owner",
+      agent_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(),
+    };
+
+    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: "clawchat-plugin-openclaw",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        ownerUserId: "owner-u",
+        groupMode: "all",
+        groupCommandMode: "owner",
+        groups: {},
+        forwardThinking: true,
+        forwardToolCalls: false,
+        richInteractions: false,
+        allowFrom: [],
+        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("clawchat-plugin-openclaw:chat-1");
+    expect(capturedCtx?.OriginatingTo).toBe("clawchat-plugin-openclaw: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("## ClawChat Agent Owner Metadata");
+    expect(directPrompt).toContain("agent_owner_nickname: Owner");
+    expect(directPrompt).toContain("## ClawChat Agent Behavior");
+    expect(directPrompt).toContain("Always be Hermes.");
+    expect(directPrompt).toContain("## ClawChat Peer Profile");
+    expect(directPrompt).toContain("sender_profile_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("\n[message]\n");
+    expect(directPrompt).toContain("sender_is_agent_owner:");
+    expect(directPrompt).toContain("sender_id: user-1");
+    expect(directPrompt).toContain("sender_profile_type: agent");
+    expect(directPrompt).toContain("sender_is_agent_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(),
+    };
+
+    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: "clawchat-plugin-openclaw",
+          enabled: true,
+          configured: true,
+          websocketUrl: "ws://t",
+          baseUrl: "https://api.example.com",
+          token: "tk",
+          userId: "u",
+          ownerUserId: "owner-u",
+          groupMode: "all",
+          groupCommandMode: "owner",
+          groups: {},
+          forwardThinking: true,
+          forwardToolCalls: false,
+          richInteractions: false,
+          allowFrom: [],
+          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("clawchat-plugin-openclaw:group:grp-1"));
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+
+    expect(capturedCtx?.From).toBe("clawchat-plugin-openclaw:group:grp-1");
+    expect(capturedCtx?.OriginatingTo).toBe("clawchat-plugin-openclaw: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("\n[message]\n");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("[message]");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("## ClawChat Group Profile/Regulation");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("profile_id: grp-1");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("\n[message]\n");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("## Current ClawChat Group Batch");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("[message]");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("group_id: grp-1");
+    expect(capturedCtx?.GroupSystemPrompt).not.toContain("was_mentioned:");
+    expect(capturedCtx?.GroupSystemPrompt).toContain("mentioned_users:");
+    expect(capturedCtx?.GroupSystemPrompt).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("\n[message]\n");
+    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_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\nfirst");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u2\nsender_name: user-2\nsender_profile_type: agent\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\nsecond");
+      expect(ctx.RawBody).not.toContain("sender_relation");
+      expect(ctx.RawBody).not.toContain("[msg-");
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("\n[message]\n"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("response_decision: Decide whether this group input needs a reply from this agent. Group batch visibility does not mean this agent was addressed."));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("allowed_outputs: normal_reply OR no_reply_token"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("no_reply_token: <clawchat:no-reply/>"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("no_reply_protocol: If you choose not to reply, output only the no-reply token. Do not describe silence with parenthesized text."));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("silent_response:"));
+      expect(ctx.GroupSystemPrompt).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(),
+      };
+      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_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\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_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: true\nmentioned_users: u\ntext:\nurgent");
+      expect(ctx.WasMentioned).toBe(true);
+      expect(ctx.MentionedUserIds).toEqual(["u"]);
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("\n[message]\n"));
+
+      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_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: false\nmentioned_users: -\ntext:\ncontext");
+      expect(ctx.RawBody).toContain("[message]\nsender_id: u2\nsender_name: user-2\nsender_profile_type: user\nsender_is_agent_owner: false\nsender_is_group_owner: false\nmentions_current_agent: true\nmentioned_users: 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("\n[message]\n"));
+      expect(ctx.GroupSystemPrompt).not.toEqual(expect.stringContaining("was_mentioned:"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("mentioned_users:"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("response_decision: Decide whether this group input needs a reply from this agent. Group batch visibility does not mean this agent was addressed."));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("allowed_outputs: normal_reply OR no_reply_token"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("no_reply_token: <clawchat:no-reply/>"));
+      expect(ctx.GroupSystemPrompt).not.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).toEqual(expect.stringContaining("sender_id: u2"));
+
+      await vi.advanceTimersByTimeAsync(30000);
+      expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  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,
+      });
+
+      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("\n[message]\n"));
+      expect(ctx.GroupSystemPrompt).toEqual(expect.stringContaining("mentioned_users: other-user"));
+      expect(ctx.RawBody).toContain("mentions_current_agent: false\nmentioned_users: other-user");
+
+      abortController.abort();
+      await startPromise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  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)),
+    });
+    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("\n[message]\n"),
+    });
+  });
+
+  it("ignores message.done lifecycle frames in 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: 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>; 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(),
+          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,
+    });
+
+    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();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.done",
+        trace_id: "done-1",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
+        payload: {
+          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((resolve) => setTimeout(resolve, 10));
+    abortController.abort();
+    await run;
+
+    expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+    expect(renderClawChatPromptInjectionForSession("s")).toBeUndefined();
+  });
+});
+
+describe("clawchat-plugin-openclaw 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(() => ({
+            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(() => {
+            throw new Error("dispatcher setup failed");
+          }),
+          withReplyDispatcher: vi.fn(),
+          dispatchReplyFromConfig: vi.fn(),
+        },
+        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 startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: vi.fn(), error: logError },
+      transport,
+    });
+
+    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: "tm",
+        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-setup-fail",
+          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((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(runtime.channel.reply.dispatchReplyFromConfig).not.toHaveBeenCalled();
+    expect(renderClawChatPromptInjectionForSession("s")).toBeUndefined();
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("clawchat-plugin-openclaw message handler error"),
+    );
+  });
+
+  it("marks dispatch idle when reply dispatch fails", async () => {
+    const markDispatchIdle = vi.fn();
+    const withReplyDispatcher = vi.fn(
+      async (opts: { run: () => Promise<unknown>; onSettled?: () => void | Promise<void> }) => {
+        try {
+          await opts.run();
+        } finally {
+          await opts.onSettled?.();
+        }
+      },
+    );
+    const dispatchReplyFromConfig = vi.fn().mockRejectedValue(new Error("dispatch boom"));
+    const logError = 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,
+          })),
+          withReplyDispatcher,
+          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 { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "clawchat-plugin-openclaw",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        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: vi.fn(), error: logError },
+      transport,
+    });
+
+    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: "tm",
+        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-fail",
+          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((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(markDispatchIdle).toHaveBeenCalledTimes(1);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("clawchat-plugin-openclaw dispatch failed msg=m-fail"),
+    );
+    const sentEvents = transport.sent.map((wire) => JSON.parse(wire) as { event: string });
+    expect(sentEvents.filter((event) => event.event === "message.send")).toEqual([]);
+  });
+});
+
+describe("clawchat-plugin-openclaw runtime connect flow", () => {
+  it("completes connect through MockTransport handshake", async () => {
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const setStatus = vi.fn();
+    const getStatus = vi.fn(() => ({ accountId: "default" }));
+
+    // Provide a stub PluginRuntime so getOpenclawClawlingRuntime() resolves inside the gateway.
+    setOpenclawClawlingRuntime({ channel: undefined } as unknown as PluginRuntime);
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "clawchat-plugin-openclaw",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "",
+        token: "tk",
+        userId: "agent-1",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        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,
+      getStatus,
+      log: { info: () => {}, error: () => {} },
+      transport,
+    });
+
+    // Give event loop one tick so connect() subscribes, then authenticate.
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "t1",
+        emitted_at: Date.now(),
+        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: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    // Let the state propagate, then abort so startOpenclawClawlingGateway resolves.
+    await new Promise((r) => setTimeout(r, 10));
+    abortController.abort();
+    await startPromise;
+
+    expect(setStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ connected: true, running: true }),
+    );
+  });
+});