@openclaw/matrix 2026.2.24 → 2026.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.25
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.24
 
 ### Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.2.24",
+  "version": "2026.3.1",
   "description": "OpenClaw Matrix channel plugin",
   "type": "module",
   "dependencies": {

package/src/config-schema.ts

@@ -37,6 +37,8 @@ const matrixRoomSchema = z
 export const MatrixConfigSchema = z.object({
   name: z.string().optional(),
   enabled: z.boolean().optional(),
+  defaultAccount: z.string().optional(),
+  accounts: z.record(z.string(), z.unknown()).optional(),
   markdown: MarkdownConfigSchema,
   homeserver: z.string().optional(),
   userId: z.string().optional(),

package/src/directory-live.test.ts

@@ -71,4 +71,15 @@ describe("matrix directory live", () => {
     expect(result).toEqual([]);
     expect(resolveMatrixAuth).not.toHaveBeenCalled();
   });
+
+  it("preserves original casing for room IDs without :server suffix", async () => {
+    const mixedCaseId = "!EonMPPbOuhntHEHgZ2dnBO-c_EglMaXlIh2kdo8cgiA";
+    const result = await listMatrixDirectoryGroupsLive({
+      cfg,
+      query: mixedCaseId,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].id).toBe(mixedCaseId);
+  });
 });

package/src/directory-live.ts

@@ -174,7 +174,8 @@ export async function listMatrixDirectoryGroupsLive(
   }
 
   if (query.startsWith("!")) {
-    return [createGroupDirectoryEntry({ id: query, name: query })];
+    const originalId = params.query?.trim() ?? query;
+    return [createGroupDirectoryEntry({ id: originalId, name: originalId })];
   }
 
   const joined = await fetchMatrixJson<MatrixJoinedRoomsResponse>({

package/src/matrix/accounts.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { CoreConfig } from "../types.js";
-import { resolveMatrixAccount } from "./accounts.js";
+import { resolveDefaultMatrixAccountId, resolveMatrixAccount } from "./accounts.js";
 
 vi.mock("./credentials.js", () => ({
   loadMatrixCredentials: () => null,
@@ -80,3 +80,52 @@ describe("resolveMatrixAccount", () => {
     expect(account.configured).toBe(true);
   });
 });
+
+describe("resolveDefaultMatrixAccountId", () => {
+  it("prefers channels.matrix.defaultAccount when it matches a configured account", () => {
+    const cfg: CoreConfig = {
+      channels: {
+        matrix: {
+          defaultAccount: "alerts",
+          accounts: {
+            default: { homeserver: "https://matrix.example.org", accessToken: "tok-default" },
+            alerts: { homeserver: "https://matrix.example.org", accessToken: "tok-alerts" },
+          },
+        },
+      },
+    };
+
+    expect(resolveDefaultMatrixAccountId(cfg)).toBe("alerts");
+  });
+
+  it("normalizes channels.matrix.defaultAccount before lookup", () => {
+    const cfg: CoreConfig = {
+      channels: {
+        matrix: {
+          defaultAccount: "Team Alerts",
+          accounts: {
+            "team-alerts": { homeserver: "https://matrix.example.org", accessToken: "tok-alerts" },
+          },
+        },
+      },
+    };
+
+    expect(resolveDefaultMatrixAccountId(cfg)).toBe("team-alerts");
+  });
+
+  it("falls back when channels.matrix.defaultAccount is not configured", () => {
+    const cfg: CoreConfig = {
+      channels: {
+        matrix: {
+          defaultAccount: "missing",
+          accounts: {
+            default: { homeserver: "https://matrix.example.org", accessToken: "tok-default" },
+            alerts: { homeserver: "https://matrix.example.org", accessToken: "tok-alerts" },
+          },
+        },
+      },
+    };
+
+    expect(resolveDefaultMatrixAccountId(cfg)).toBe("default");
+  });
+});

package/src/matrix/accounts.ts

@@ -1,4 +1,8 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "openclaw/plugin-sdk/account-id";
 import type { CoreConfig, MatrixConfig } from "../types.js";
 import { resolveMatrixConfigForAccount } from "./client.js";
 import { credentialsMatchConfig, loadMatrixCredentials } from "./credentials.js";
@@ -16,6 +20,7 @@ function mergeAccountConfig(base: MatrixConfig, account: MatrixConfig): MatrixCo
   }
   // Don't propagate the accounts map into the merged per-account config
   delete (merged as Record<string, unknown>).accounts;
+  delete (merged as Record<string, unknown>).defaultAccount;
   return merged;
 }
 
@@ -54,6 +59,13 @@ export function listMatrixAccountIds(cfg: CoreConfig): string[] {
 }
 
 export function resolveDefaultMatrixAccountId(cfg: CoreConfig): string {
+  const preferred = normalizeOptionalAccountId(cfg.channels?.matrix?.defaultAccount);
+  if (
+    preferred &&
+    listMatrixAccountIds(cfg).some((accountId) => normalizeAccountId(accountId) === preferred)
+  ) {
+    return preferred;
+  }
   const ids = listMatrixAccountIds(cfg);
   if (ids.includes(DEFAULT_ACCOUNT_ID)) {
     return DEFAULT_ACCOUNT_ID;

package/src/matrix/client/shared.test.ts

@@ -0,0 +1,85 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveSharedMatrixClient, stopSharedClient } from "./shared.js";
+import type { MatrixAuth } from "./types.js";
+
+const createMatrixClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./create-client.js", () => ({
+  createMatrixClient: (...args: unknown[]) => createMatrixClientMock(...args),
+}));
+
+function makeAuth(suffix: string): MatrixAuth {
+  return {
+    homeserver: "https://matrix.example.org",
+    userId: `@bot-${suffix}:example.org`,
+    accessToken: `token-${suffix}`,
+    encryption: false,
+  };
+}
+
+function createMockClient(startImpl: () => Promise<void>): MatrixClient {
+  return {
+    start: vi.fn(startImpl),
+    stop: vi.fn(),
+    getJoinedRooms: vi.fn().mockResolvedValue([]),
+    crypto: undefined,
+  } as unknown as MatrixClient;
+}
+
+describe("resolveSharedMatrixClient startup behavior", () => {
+  afterEach(() => {
+    stopSharedClient();
+    createMatrixClientMock.mockReset();
+    vi.useRealTimers();
+  });
+
+  it("propagates the original start error during initialization", async () => {
+    vi.useFakeTimers();
+    const startError = new Error("bad token");
+    const client = createMockClient(
+      () =>
+        new Promise<void>((_resolve, reject) => {
+          setTimeout(() => reject(startError), 1);
+        }),
+    );
+    createMatrixClientMock.mockResolvedValue(client);
+
+    const startPromise = resolveSharedMatrixClient({
+      auth: makeAuth("start-error"),
+    });
+    const startExpectation = expect(startPromise).rejects.toBe(startError);
+
+    await vi.advanceTimersByTimeAsync(2001);
+    await startExpectation;
+  });
+
+  it("retries start after a late start-loop failure", async () => {
+    vi.useFakeTimers();
+    let rejectFirstStart: ((err: unknown) => void) | undefined;
+    const firstStart = new Promise<void>((_resolve, reject) => {
+      rejectFirstStart = reject;
+    });
+    const secondStart = new Promise<void>(() => {});
+    const startMock = vi.fn().mockReturnValueOnce(firstStart).mockReturnValueOnce(secondStart);
+    const client = createMockClient(startMock);
+    createMatrixClientMock.mockResolvedValue(client);
+
+    const firstResolve = resolveSharedMatrixClient({
+      auth: makeAuth("late-failure"),
+    });
+    await vi.advanceTimersByTimeAsync(2000);
+    await expect(firstResolve).resolves.toBe(client);
+    expect(startMock).toHaveBeenCalledTimes(1);
+
+    rejectFirstStart?.(new Error("late failure"));
+    await Promise.resolve();
+
+    const secondResolve = resolveSharedMatrixClient({
+      auth: makeAuth("late-failure"),
+    });
+    await vi.advanceTimersByTimeAsync(2000);
+    await expect(secondResolve).resolves.toBe(client);
+    expect(startMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/matrix/client/shared.ts

@@ -4,6 +4,7 @@ import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 import type { CoreConfig } from "../../types.js";
 import { resolveMatrixAuth } from "./config.js";
 import { createMatrixClient } from "./create-client.js";
+import { startMatrixClientWithGrace } from "./startup.js";
 import { DEFAULT_ACCOUNT_KEY } from "./storage.js";
 import type { MatrixAuth } from "./types.js";
 
@@ -84,7 +85,13 @@ async function ensureSharedClientStarted(params: {
       }
     }
 
-    await client.start();
+    await startMatrixClientWithGrace({
+      client,
+      onError: (err: unknown) => {
+        params.state.started = false;
+        LogService.error("MatrixClientLite", "client.start() error:", err);
+      },
+    });
     params.state.started = true;
   })();
   sharedClientStartPromises.set(key, startPromise);

package/src/matrix/client/startup.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import { MATRIX_CLIENT_STARTUP_GRACE_MS, startMatrixClientWithGrace } from "./startup.js";
+
+describe("startMatrixClientWithGrace", () => {
+  it("resolves after grace when start loop keeps running", async () => {
+    vi.useFakeTimers();
+    const client = {
+      start: vi.fn().mockReturnValue(new Promise<void>(() => {})),
+    };
+    const startPromise = startMatrixClientWithGrace({ client });
+    await vi.advanceTimersByTimeAsync(MATRIX_CLIENT_STARTUP_GRACE_MS);
+    await expect(startPromise).resolves.toBeUndefined();
+    vi.useRealTimers();
+  });
+
+  it("rejects when startup fails during grace", async () => {
+    vi.useFakeTimers();
+    const startError = new Error("invalid token");
+    const client = {
+      start: vi.fn().mockRejectedValue(startError),
+    };
+    const startPromise = startMatrixClientWithGrace({ client });
+    const startupExpectation = expect(startPromise).rejects.toBe(startError);
+    await vi.advanceTimersByTimeAsync(MATRIX_CLIENT_STARTUP_GRACE_MS);
+    await startupExpectation;
+    vi.useRealTimers();
+  });
+
+  it("calls onError for late failures after startup returns", async () => {
+    vi.useFakeTimers();
+    const lateError = new Error("late disconnect");
+    let rejectStart: ((err: unknown) => void) | undefined;
+    const startLoop = new Promise<void>((_resolve, reject) => {
+      rejectStart = reject;
+    });
+    const onError = vi.fn();
+    const client = {
+      start: vi.fn().mockReturnValue(startLoop),
+    };
+    const startPromise = startMatrixClientWithGrace({ client, onError });
+    await vi.advanceTimersByTimeAsync(MATRIX_CLIENT_STARTUP_GRACE_MS);
+    await expect(startPromise).resolves.toBeUndefined();
+
+    rejectStart?.(lateError);
+    await Promise.resolve();
+    expect(onError).toHaveBeenCalledWith(lateError);
+    vi.useRealTimers();
+  });
+});

package/src/matrix/client/startup.ts

@@ -0,0 +1,29 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+
+export const MATRIX_CLIENT_STARTUP_GRACE_MS = 2000;
+
+export async function startMatrixClientWithGrace(params: {
+  client: Pick<MatrixClient, "start">;
+  graceMs?: number;
+  onError?: (err: unknown) => void;
+}): Promise<void> {
+  const graceMs = params.graceMs ?? MATRIX_CLIENT_STARTUP_GRACE_MS;
+  let startFailed = false;
+  let startError: unknown = undefined;
+  let startPromise: Promise<unknown>;
+  try {
+    startPromise = params.client.start();
+  } catch (err) {
+    params.onError?.(err);
+    throw err;
+  }
+  void startPromise.catch((err: unknown) => {
+    startFailed = true;
+    startError = err;
+    params.onError?.(err);
+  });
+  await new Promise((resolve) => setTimeout(resolve, graceMs));
+  if (startFailed) {
+    throw startError;
+  }
+}

package/src/matrix/client-bootstrap.ts

@@ -1,4 +1,6 @@
-import { createMatrixClient } from "./client.js";
+import { LogService } from "@vector-im/matrix-bot-sdk";
+import { createMatrixClient } from "./client/create-client.js";
+import { startMatrixClientWithGrace } from "./client/startup.js";
 
 type MatrixClientBootstrapAuth = {
   homeserver: string;
@@ -34,6 +36,11 @@ export async function createPreparedMatrixClient(opts: {
       // Ignore crypto prep failures for one-off requests.
     }
   }
-  await client.start();
+  await startMatrixClientWithGrace({
+    client,
+    onError: (err: unknown) => {
+      LogService.error("MatrixClientBootstrap", "client.start() error:", err);
+    },
+  });
   return client;
 }

package/src/matrix/monitor/access-policy.ts

@@ -0,0 +1,127 @@
+import {
+  formatAllowlistMatchMeta,
+  issuePairingChallenge,
+  readStoreAllowFromForDmPolicy,
+  resolveDmGroupAccessWithLists,
+} from "openclaw/plugin-sdk";
+import {
+  normalizeMatrixAllowList,
+  resolveMatrixAllowListMatch,
+  resolveMatrixAllowListMatches,
+} from "./allowlist.js";
+
+type MatrixDmPolicy = "open" | "pairing" | "allowlist" | "disabled";
+type MatrixGroupPolicy = "open" | "allowlist" | "disabled";
+
+export async function resolveMatrixAccessState(params: {
+  isDirectMessage: boolean;
+  resolvedAccountId: string;
+  dmPolicy: MatrixDmPolicy;
+  groupPolicy: MatrixGroupPolicy;
+  allowFrom: string[];
+  groupAllowFrom: Array<string | number>;
+  senderId: string;
+  readStoreForDmPolicy: (provider: string, accountId: string) => Promise<string[]>;
+}) {
+  const storeAllowFrom = params.isDirectMessage
+    ? await readStoreAllowFromForDmPolicy({
+        provider: "matrix",
+        accountId: params.resolvedAccountId,
+        dmPolicy: params.dmPolicy,
+        readStore: params.readStoreForDmPolicy,
+      })
+    : [];
+  const normalizedGroupAllowFrom = normalizeMatrixAllowList(params.groupAllowFrom);
+  const senderGroupPolicy =
+    params.groupPolicy === "disabled"
+      ? "disabled"
+      : normalizedGroupAllowFrom.length > 0
+        ? "allowlist"
+        : "open";
+  const access = resolveDmGroupAccessWithLists({
+    isGroup: !params.isDirectMessage,
+    dmPolicy: params.dmPolicy,
+    groupPolicy: senderGroupPolicy,
+    allowFrom: params.allowFrom,
+    groupAllowFrom: normalizedGroupAllowFrom,
+    storeAllowFrom,
+    groupAllowFromFallbackToAllowFrom: false,
+    isSenderAllowed: (allowFrom) =>
+      resolveMatrixAllowListMatches({
+        allowList: normalizeMatrixAllowList(allowFrom),
+        userId: params.senderId,
+      }),
+  });
+  const effectiveAllowFrom = normalizeMatrixAllowList(access.effectiveAllowFrom);
+  const effectiveGroupAllowFrom = normalizeMatrixAllowList(access.effectiveGroupAllowFrom);
+  return {
+    access,
+    effectiveAllowFrom,
+    effectiveGroupAllowFrom,
+    groupAllowConfigured: effectiveGroupAllowFrom.length > 0,
+  };
+}
+
+export async function enforceMatrixDirectMessageAccess(params: {
+  dmEnabled: boolean;
+  dmPolicy: MatrixDmPolicy;
+  accessDecision: "allow" | "block" | "pairing";
+  senderId: string;
+  senderName: string;
+  effectiveAllowFrom: string[];
+  upsertPairingRequest: (input: {
+    id: string;
+    meta?: Record<string, string | undefined>;
+  }) => Promise<{
+    code: string;
+    created: boolean;
+  }>;
+  sendPairingReply: (text: string) => Promise<void>;
+  logVerboseMessage: (message: string) => void;
+}): Promise<boolean> {
+  if (!params.dmEnabled) {
+    return false;
+  }
+  if (params.accessDecision === "allow") {
+    return true;
+  }
+  const allowMatch = resolveMatrixAllowListMatch({
+    allowList: params.effectiveAllowFrom,
+    userId: params.senderId,
+  });
+  const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
+  if (params.accessDecision === "pairing") {
+    await issuePairingChallenge({
+      channel: "matrix",
+      senderId: params.senderId,
+      senderIdLine: `Matrix user id: ${params.senderId}`,
+      meta: { name: params.senderName },
+      upsertPairingRequest: params.upsertPairingRequest,
+      buildReplyText: ({ code }) =>
+        [
+          "OpenClaw: access not configured.",
+          "",
+          `Pairing code: ${code}`,
+          "",
+          "Ask the bot owner to approve with:",
+          "openclaw pairing approve matrix <code>",
+        ].join("\n"),
+      sendPairingReply: params.sendPairingReply,
+      onCreated: () => {
+        params.logVerboseMessage(
+          `matrix pairing request sender=${params.senderId} name=${params.senderName ?? "unknown"} (${allowMatchMeta})`,
+        );
+      },
+      onReplyError: (err) => {
+        params.logVerboseMessage(
+          `matrix pairing reply failed for ${params.senderId}: ${String(err)}`,
+        );
+      },
+    });
+    return false;
+  }
+  params.logVerboseMessage(
+    `matrix: blocked dm sender ${params.senderId} (dmPolicy=${params.dmPolicy}, ${allowMatchMeta})`,
+  );
+  return false;
+}

package/src/matrix/monitor/direct.test.ts

@@ -0,0 +1,65 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { createDirectRoomTracker } from "./direct.js";
+
+function createMockClient(params: {
+  isDm?: boolean;
+  senderDirect?: boolean;
+  selfDirect?: boolean;
+  members?: string[];
+}) {
+  const members = params.members ?? ["@alice:example.org", "@bot:example.org"];
+  return {
+    dms: {
+      update: vi.fn().mockResolvedValue(undefined),
+      isDm: vi.fn().mockReturnValue(params.isDm === true),
+    },
+    getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+    getJoinedRoomMembers: vi.fn().mockResolvedValue(members),
+    getRoomStateEvent: vi
+      .fn()
+      .mockImplementation(async (_roomId: string, _event: string, stateKey: string) => {
+        if (stateKey === "@alice:example.org") {
+          return { is_direct: params.senderDirect === true };
+        }
+        if (stateKey === "@bot:example.org") {
+          return { is_direct: params.selfDirect === true };
+        }
+        return {};
+      }),
+  } as unknown as MatrixClient;
+}
+
+describe("createDirectRoomTracker", () => {
+  it("treats m.direct rooms as DMs", async () => {
+    const tracker = createDirectRoomTracker(createMockClient({ isDm: true }));
+    await expect(
+      tracker.isDirectMessage({
+        roomId: "!room:example.org",
+        senderId: "@alice:example.org",
+      }),
+    ).resolves.toBe(true);
+  });
+
+  it("does not classify 2-member rooms as DMs without direct flags", async () => {
+    const client = createMockClient({ isDm: false });
+    const tracker = createDirectRoomTracker(client);
+    await expect(
+      tracker.isDirectMessage({
+        roomId: "!room:example.org",
+        senderId: "@alice:example.org",
+      }),
+    ).resolves.toBe(false);
+    expect(client.getJoinedRoomMembers).not.toHaveBeenCalled();
+  });
+
+  it("uses is_direct member flags when present", async () => {
+    const tracker = createDirectRoomTracker(createMockClient({ senderDirect: true }));
+    await expect(
+      tracker.isDirectMessage({
+        roomId: "!room:example.org",
+        senderId: "@alice:example.org",
+      }),
+    ).resolves.toBe(true);
+  });
+});

package/src/matrix/monitor/direct.ts

@@ -8,15 +8,19 @@ type DirectMessageCheck = {
 
 type DirectRoomTrackerOptions = {
   log?: (message: string) => void;
+  includeMemberCountInLogs?: boolean;
 };
 
 const DM_CACHE_TTL_MS = 30_000;
 
 export function createDirectRoomTracker(client: MatrixClient, opts: DirectRoomTrackerOptions = {}) {
   const log = opts.log ?? (() => {});
+  const includeMemberCountInLogs = opts.includeMemberCountInLogs === true;
   let lastDmUpdateMs = 0;
   let cachedSelfUserId: string | null = null;
-  const memberCountCache = new Map<string, { count: number; ts: number }>();
+  const memberCountCache = includeMemberCountInLogs
+    ? new Map<string, { count: number; ts: number }>()
+    : undefined;
 
   const ensureSelfUserId = async (): Promise<string | null> => {
     if (cachedSelfUserId) {
@@ -44,6 +48,9 @@ export function createDirectRoomTracker(client: MatrixClient, opts: DirectRoomTr
   };
 
   const resolveMemberCount = async (roomId: string): Promise<number | null> => {
+    if (!memberCountCache) {
+      return null;
+    }
     const cached = memberCountCache.get(roomId);
     const now = Date.now();
     if (cached && now - cached.ts < DM_CACHE_TTL_MS) {
@@ -78,17 +85,13 @@ export function createDirectRoomTracker(client: MatrixClient, opts: DirectRoomTr
       const { roomId, senderId } = params;
       await refreshDmCache();
 
+      // Check m.direct account data (most authoritative)
       if (client.dms.isDm(roomId)) {
         log(`matrix: dm detected via m.direct room=${roomId}`);
         return true;
       }
 
-      const memberCount = await resolveMemberCount(roomId);
-      if (memberCount === 2) {
-        log(`matrix: dm detected via member count room=${roomId} members=${memberCount}`);
-        return true;
-      }
-
+      // Check m.room.member state for is_direct flag
       const selfUserId = params.selfUserId ?? (await ensureSelfUserId());
       const directViaState =
         (await hasDirectFlag(roomId, senderId)) || (await hasDirectFlag(roomId, selfUserId ?? ""));
@@ -97,6 +100,16 @@ export function createDirectRoomTracker(client: MatrixClient, opts: DirectRoomTr
         return true;
       }
 
+      // Member count alone is NOT a reliable DM indicator.
+      // Explicitly configured group rooms with 2 members (e.g. bot + one user)
+      // were being misclassified as DMs, causing messages to be routed through
+      // DM policy instead of group policy and silently dropped.
+      // See: https://github.com/openclaw/openclaw/issues/20145
+      if (!includeMemberCountInLogs) {
+        log(`matrix: dm check room=${roomId} result=group`);
+        return false;
+      }
+      const memberCount = await resolveMemberCount(roomId);
       log(`matrix: dm check room=${roomId} result=group members=${memberCount ?? "unknown"}`);
       return false;
     },

package/src/matrix/monitor/events.test.ts

@@ -138,4 +138,35 @@ describe("registerMatrixMonitorEvents", () => {
     expect(getUserId).toHaveBeenCalledTimes(1);
     expect(sendReadReceiptMatrixMock).not.toHaveBeenCalled();
   });
+
+  it("skips duplicate listener registration for the same client", () => {
+    const handlers = new Map<string, (...args: unknown[]) => void>();
+    const onMock = vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      handlers.set(event, handler);
+    });
+    const client = {
+      on: onMock,
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      crypto: undefined,
+    } as unknown as MatrixClient;
+    const params = {
+      client,
+      auth: { encryption: false } as MatrixAuth,
+      logVerboseMessage: vi.fn(),
+      warnedEncryptedRooms: new Set<string>(),
+      warnedCryptoMissingRooms: new Set<string>(),
+      logger: { warn: vi.fn() } as unknown as RuntimeLogger,
+      formatNativeDependencyHint: (() =>
+        "") as PluginRuntime["system"]["formatNativeDependencyHint"],
+      onRoomMessage: vi.fn(),
+    };
+    registerMatrixMonitorEvents(params);
+    const initialCallCount = onMock.mock.calls.length;
+    registerMatrixMonitorEvents(params);
+
+    expect(onMock).toHaveBeenCalledTimes(initialCallCount);
+    expect(params.logVerboseMessage).toHaveBeenCalledWith(
+      "matrix: skipping duplicate listener registration for client",
+    );
+  });
 });