@openclaw/matrix 2026.2.25 → 2026.3.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026.3.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 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

package/index.ts

@@ -1,6 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { matrixPlugin } from "./src/channel.js";
+import { ensureMatrixCryptoRuntime } from "./src/matrix/deps.js";
 import { setMatrixRuntime } from "./src/runtime.js";
 
 const plugin = {
@@ -10,6 +11,10 @@ const plugin = {
   configSchema: emptyPluginConfigSchema(),
   register(api: OpenClawPluginApi) {
     setMatrixRuntime(api.runtime);
+    void ensureMatrixCryptoRuntime({ log: api.logger.info }).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      api.logger.warn?.(`matrix: crypto runtime bootstrap failed: ${message}`);
+    });
     api.registerChannel({ plugin: matrixPlugin });
   },
 };

package/package.json

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

package/src/channel.ts

@@ -1,6 +1,7 @@
 import {
   applyAccountNameToChannelSection,
   buildChannelConfigSchema,
+  buildProbeChannelStatusSummary,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
   formatPairingApproveHint,
@@ -32,6 +33,7 @@ import { sendMessageMatrix } from "./matrix/send.js";
 import { matrixOnboardingAdapter } from "./onboarding.js";
 import { matrixOutbound } from "./outbound.js";
 import { resolveMatrixTargets } from "./resolve-targets.js";
+import { normalizeSecretInputString } from "./secret-input.js";
 import type { CoreConfig } from "./types.js";
 
 // Mutex for serializing account startup (workaround for concurrent dynamic import race condition)
@@ -325,7 +327,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         return "Matrix requires --homeserver";
       }
       const accessToken = input.accessToken?.trim();
-      const password = input.password?.trim();
+      const password = normalizeSecretInputString(input.password);
       const userId = input.userId?.trim();
       if (!accessToken && !password) {
         return "Matrix requires --access-token or --password";
@@ -363,7 +365,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
         homeserver: input.homeserver?.trim(),
         userId: input.userId?.trim(),
         accessToken: input.accessToken?.trim(),
-        password: input.password?.trim(),
+        password: normalizeSecretInputString(input.password),
         deviceName: input.deviceName?.trim(),
         initialSyncLimit: input.initialSyncLimit,
       });
@@ -393,16 +395,8 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
           },
         ];
       }),
-    buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
-      baseUrl: snapshot.baseUrl ?? null,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
-      probe: snapshot.probe,
-      lastProbeAt: snapshot.lastProbeAt ?? null,
-    }),
+    buildChannelSummary: ({ snapshot }) =>
+      buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
     probeAccount: async ({ account, timeoutMs, cfg }) => {
       try {
         const auth = await resolveMatrixAuth({

package/src/config-schema.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { MatrixConfigSchema } from "./config-schema.js";
+
+describe("MatrixConfigSchema SecretInput", () => {
+  it("accepts SecretRef password at top-level", () => {
+    const result = MatrixConfigSchema.safeParse({
+      homeserver: "https://matrix.example.org",
+      userId: "@bot:example.org",
+      password: { source: "env", provider: "default", id: "MATRIX_PASSWORD" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts SecretRef password on account", () => {
+    const result = MatrixConfigSchema.safeParse({
+      accounts: {
+        work: {
+          homeserver: "https://matrix.example.org",
+          userId: "@bot:example.org",
+          password: { source: "env", provider: "default", id: "MATRIX_WORK_PASSWORD" },
+        },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -1,5 +1,6 @@
 import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk";
 import { z } from "zod";
+import { buildSecretInputSchema } from "./secret-input.js";
 
 const allowFromEntry = z.union([z.string(), z.number()]);
 
@@ -37,11 +38,13 @@ 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(),
   accessToken: z.string().optional(),
-  password: z.string().optional(),
+  password: buildSecretInputSchema().optional(),
   deviceName: z.string().optional(),
   initialSyncLimit: z.number().optional(),
   encryption: z.boolean().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,9 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "openclaw/plugin-sdk/account-id";
+import { hasConfiguredSecretInput } from "../secret-input.js";
 import type { CoreConfig, MatrixConfig } from "../types.js";
 import { resolveMatrixConfigForAccount } from "./client.js";
 import { credentialsMatchConfig, loadMatrixCredentials } from "./credentials.js";
@@ -16,6 +21,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 +60,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;
@@ -94,7 +107,7 @@ export function resolveMatrixAccount(params: {
   const hasUserId = Boolean(resolved.userId);
   const hasAccessToken = Boolean(resolved.accessToken);
   const hasPassword = Boolean(resolved.password);
-  const hasPasswordAuth = hasUserId && hasPassword;
+  const hasPasswordAuth = hasUserId && (hasPassword || hasConfiguredSecretInput(base.password));
   const stored = loadMatrixCredentials(process.env, accountId);
   const hasStored =
     stored && resolved.homeserver

package/src/matrix/client/config.ts

@@ -1,12 +1,17 @@
-import { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 import { getMatrixRuntime } from "../../runtime.js";
+import {
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "../../secret-input.js";
 import type { CoreConfig } from "../../types.js";
+import { loadMatrixSdk } from "../sdk-runtime.js";
 import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
 import type { MatrixAuth, MatrixResolvedConfig } from "./types.js";
 
-function clean(value?: string): string {
-  return value?.trim() ?? "";
+function clean(value: unknown, path: string): string {
+  return normalizeResolvedSecretInputString({ value, path }) ?? "";
 }
 
 /** Shallow-merge known nested config sub-objects so partial overrides inherit base values. */
@@ -52,11 +57,23 @@ export function resolveMatrixConfigForAccount(
   // nested object inheritance (dm, actions, groups) so partial overrides work.
   const matrix = accountConfig ? deepMergeConfig(matrixBase, accountConfig) : matrixBase;
 
-  const homeserver = clean(matrix.homeserver) || clean(env.MATRIX_HOMESERVER);
-  const userId = clean(matrix.userId) || clean(env.MATRIX_USER_ID);
-  const accessToken = clean(matrix.accessToken) || clean(env.MATRIX_ACCESS_TOKEN) || undefined;
-  const password = clean(matrix.password) || clean(env.MATRIX_PASSWORD) || undefined;
-  const deviceName = clean(matrix.deviceName) || clean(env.MATRIX_DEVICE_NAME) || undefined;
+  const homeserver =
+    clean(matrix.homeserver, "channels.matrix.homeserver") ||
+    clean(env.MATRIX_HOMESERVER, "MATRIX_HOMESERVER");
+  const userId =
+    clean(matrix.userId, "channels.matrix.userId") || clean(env.MATRIX_USER_ID, "MATRIX_USER_ID");
+  const accessToken =
+    clean(matrix.accessToken, "channels.matrix.accessToken") ||
+    clean(env.MATRIX_ACCESS_TOKEN, "MATRIX_ACCESS_TOKEN") ||
+    undefined;
+  const password =
+    clean(matrix.password, "channels.matrix.password") ||
+    clean(env.MATRIX_PASSWORD, "MATRIX_PASSWORD") ||
+    undefined;
+  const deviceName =
+    clean(matrix.deviceName, "channels.matrix.deviceName") ||
+    clean(env.MATRIX_DEVICE_NAME, "MATRIX_DEVICE_NAME") ||
+    undefined;
   const initialSyncLimit =
     typeof matrix.initialSyncLimit === "number"
       ? Math.max(0, Math.floor(matrix.initialSyncLimit))
@@ -119,6 +136,7 @@ export async function resolveMatrixAuth(params?: {
     if (!userId) {
       // Fetch userId from access token via whoami
       ensureMatrixSdkLoggingConfigured();
+      const { MatrixClient } = loadMatrixSdk();
       const tempClient = new MatrixClient(resolved.homeserver, resolved.accessToken);
       const whoami = await tempClient.getUserId();
       userId = whoami;
@@ -167,28 +185,36 @@ export async function resolveMatrixAuth(params?: {
     );
   }
 
-  // Login with password using HTTP API
-  const loginResponse = await fetch(`${resolved.homeserver}/_matrix/client/v3/login`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      type: "m.login.password",
-      identifier: { type: "m.id.user", user: resolved.userId },
-      password: resolved.password,
-      initial_device_display_name: resolved.deviceName ?? "OpenClaw Gateway",
-    }),
+  // Login with password using HTTP API.
+  const { response: loginResponse, release: releaseLoginResponse } = await fetchWithSsrFGuard({
+    url: `${resolved.homeserver}/_matrix/client/v3/login`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "m.login.password",
+        identifier: { type: "m.id.user", user: resolved.userId },
+        password: resolved.password,
+        initial_device_display_name: resolved.deviceName ?? "OpenClaw Gateway",
+      }),
+    },
+    auditContext: "matrix.login",
   });
-
-  if (!loginResponse.ok) {
-    const errorText = await loginResponse.text();
-    throw new Error(`Matrix login failed: ${errorText}`);
-  }
-
-  const login = (await loginResponse.json()) as {
-    access_token?: string;
-    user_id?: string;
-    device_id?: string;
-  };
+  const login = await (async () => {
+    try {
+      if (!loginResponse.ok) {
+        const errorText = await loginResponse.text();
+        throw new Error(`Matrix login failed: ${errorText}`);
+      }
+      return (await loginResponse.json()) as {
+        access_token?: string;
+        user_id?: string;
+        device_id?: string;
+      };
+    } finally {
+      await releaseLoginResponse();
+    }
+  })();
 
   const accessToken = login.access_token?.trim();
   if (!accessToken) {

package/src/matrix/client/create-client.ts

@@ -1,11 +1,10 @@
 import fs from "node:fs";
-import type { IStorageProvider, ICryptoStorageProvider } from "@vector-im/matrix-bot-sdk";
-import {
-  LogService,
+import type {
+  IStorageProvider,
+  ICryptoStorageProvider,
   MatrixClient,
-  SimpleFsStorageProvider,
-  RustSdkCryptoStorageProvider,
 } from "@vector-im/matrix-bot-sdk";
+import { loadMatrixSdk } from "../sdk-runtime.js";
 import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
 import {
   maybeMigrateLegacyStorage,
@@ -14,6 +13,7 @@ import {
 } from "./storage.js";
 
 function sanitizeUserIdList(input: unknown, label: string): string[] {
+  const LogService = loadMatrixSdk().LogService;
   if (input == null) {
     return [];
   }
@@ -44,6 +44,8 @@ export async function createMatrixClient(params: {
   localTimeoutMs?: number;
   accountId?: string | null;
 }): Promise<MatrixClient> {
+  const { MatrixClient, SimpleFsStorageProvider, RustSdkCryptoStorageProvider, LogService } =
+    loadMatrixSdk();
   ensureMatrixSdkLoggingConfigured();
   const env = process.env;
 

package/src/matrix/client/logging.ts

@@ -1,7 +1,15 @@
-import { ConsoleLogger, LogService } from "@vector-im/matrix-bot-sdk";
+import { loadMatrixSdk } from "../sdk-runtime.js";
 
 let matrixSdkLoggingConfigured = false;
-const matrixSdkBaseLogger = new ConsoleLogger();
+let matrixSdkBaseLogger:
+  | {
+      trace: (module: string, ...messageOrObject: unknown[]) => void;
+      debug: (module: string, ...messageOrObject: unknown[]) => void;
+      info: (module: string, ...messageOrObject: unknown[]) => void;
+      warn: (module: string, ...messageOrObject: unknown[]) => void;
+      error: (module: string, ...messageOrObject: unknown[]) => void;
+    }
+  | undefined;
 
 function shouldSuppressMatrixHttpNotFound(module: string, messageOrObject: unknown[]): boolean {
   if (module !== "MatrixHttpClient") {
@@ -19,18 +27,20 @@ export function ensureMatrixSdkLoggingConfigured(): void {
   if (matrixSdkLoggingConfigured) {
     return;
   }
+  const { ConsoleLogger, LogService } = loadMatrixSdk();
+  matrixSdkBaseLogger = new ConsoleLogger();
   matrixSdkLoggingConfigured = true;
 
   LogService.setLogger({
-    trace: (module, ...messageOrObject) => matrixSdkBaseLogger.trace(module, ...messageOrObject),
-    debug: (module, ...messageOrObject) => matrixSdkBaseLogger.debug(module, ...messageOrObject),
-    info: (module, ...messageOrObject) => matrixSdkBaseLogger.info(module, ...messageOrObject),
-    warn: (module, ...messageOrObject) => matrixSdkBaseLogger.warn(module, ...messageOrObject),
+    trace: (module, ...messageOrObject) => matrixSdkBaseLogger?.trace(module, ...messageOrObject),
+    debug: (module, ...messageOrObject) => matrixSdkBaseLogger?.debug(module, ...messageOrObject),
+    info: (module, ...messageOrObject) => matrixSdkBaseLogger?.info(module, ...messageOrObject),
+    warn: (module, ...messageOrObject) => matrixSdkBaseLogger?.warn(module, ...messageOrObject),
     error: (module, ...messageOrObject) => {
       if (shouldSuppressMatrixHttpNotFound(module, messageOrObject)) {
         return;
       }
-      matrixSdkBaseLogger.error(module, ...messageOrObject);
+      matrixSdkBaseLogger?.error(module, ...messageOrObject);
     },
   });
 }

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

@@ -1,9 +1,10 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import { LogService } from "@vector-im/matrix-bot-sdk";
 import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 import type { CoreConfig } from "../../types.js";
+import { getMatrixLogService } from "../sdk-runtime.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";
 
@@ -80,11 +81,19 @@ async function ensureSharedClientStarted(params: {
           params.state.cryptoReady = true;
         }
       } catch (err) {
+        const LogService = getMatrixLogService();
         LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
       }
     }
 
-    await client.start();
+    await startMatrixClientWithGrace({
+      client,
+      onError: (err: unknown) => {
+        params.state.started = false;
+        const LogService = getMatrixLogService();
+        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();
+  });
+});