@archipelagolab/lobi 1.0.0

package/src/matrix/sdk/event-helpers.ts

@@ -0,0 +1,71 @@
+import type { MatrixEvent } from "@archipelagolab/lobi-js-sdk";
+import type { MatrixRawEvent } from "./types.js";
+
+export function matrixEventToRaw(event: MatrixEvent): MatrixRawEvent {
+  const unsigned = (event.getUnsigned?.() ?? {}) as {
+    age?: number;
+    redacted_because?: unknown;
+  };
+  const raw: MatrixRawEvent = {
+    event_id: event.getId() ?? "",
+    sender: event.getSender() ?? "",
+    type: event.getType() ?? "",
+    origin_server_ts: event.getTs() ?? 0,
+    content: (event.getContent?.() ?? {}) || {},
+    unsigned,
+  };
+  const stateKey = resolveMatrixStateKey(event);
+  if (typeof stateKey === "string") {
+    raw.state_key = stateKey;
+  }
+  return raw;
+}
+
+export function parseMxc(url: string): { server: string; mediaId: string } | null {
+  const match = /^mxc:\/\/([^/]+)\/(.+)$/.exec(url.trim());
+  if (!match) {
+    return null;
+  }
+  return {
+    server: match[1],
+    mediaId: match[2],
+  };
+}
+
+export function buildHttpError(
+  statusCode: number,
+  bodyText: string,
+): Error & { statusCode: number } {
+  let message = `Matrix HTTP ${statusCode}`;
+  if (bodyText.trim()) {
+    try {
+      const parsed = JSON.parse(bodyText) as { error?: string };
+      if (typeof parsed.error === "string" && parsed.error.trim()) {
+        message = parsed.error.trim();
+      } else {
+        message = bodyText.slice(0, 500);
+      }
+    } catch {
+      message = bodyText.slice(0, 500);
+    }
+  }
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function resolveMatrixStateKey(event: MatrixEvent): string | undefined {
+  const direct = event.getStateKey?.();
+  if (typeof direct === "string") {
+    return direct;
+  }
+  const wireContent = (
+    event as { getWireContent?: () => { state_key?: unknown } }
+  ).getWireContent?.();
+  if (wireContent && typeof wireContent.state_key === "string") {
+    return wireContent.state_key;
+  }
+  const rawEvent = (event as { event?: { state_key?: unknown } }).event;
+  if (rawEvent && typeof rawEvent.state_key === "string") {
+    return rawEvent.state_key;
+  }
+  return undefined;
+}

package/src/matrix/sdk/http-client.test.ts

@@ -0,0 +1,134 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { performMatrixRequestMock } = vi.hoisted(() => ({
+  performMatrixRequestMock: vi.fn(),
+}));
+
+vi.mock("./transport.js", () => ({
+  performMatrixRequest: performMatrixRequestMock,
+}));
+
+let MatrixAuthedHttpClient: typeof import("./http-client.js").MatrixAuthedHttpClient;
+
+describe("MatrixAuthedHttpClient", () => {
+  beforeAll(async () => {
+    ({ MatrixAuthedHttpClient } = await import("./http-client.js"));
+  });
+
+  beforeEach(() => {
+    performMatrixRequestMock.mockReset();
+  });
+
+  it("parses JSON responses and forwards absolute-endpoint opt-in", async () => {
+    performMatrixRequestMock.mockResolvedValue({
+      response: new Response('{"ok":true}', {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+      text: '{"ok":true}',
+      buffer: Buffer.from('{"ok":true}', "utf8"),
+    });
+
+    const client = new MatrixAuthedHttpClient({
+      homeserver: "https://matrix.example.org",
+      accessToken: "token",
+      ssrfPolicy: {
+        allowPrivateNetwork: true,
+      },
+      dispatcherPolicy: {
+        mode: "explicit-proxy",
+        proxyUrl: "http://proxy.internal:8080",
+      },
+    });
+    const result = await client.requestJson({
+      method: "GET",
+      endpoint: "https://matrix.example.org/_lobi/client/v3/account/whoami",
+      timeoutMs: 5000,
+      allowAbsoluteEndpoint: true,
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(performMatrixRequestMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "GET",
+        endpoint: "https://matrix.example.org/_lobi/client/v3/account/whoami",
+        allowAbsoluteEndpoint: true,
+        ssrfPolicy: { allowPrivateNetwork: true },
+        dispatcherPolicy: {
+          mode: "explicit-proxy",
+          proxyUrl: "http://proxy.internal:8080",
+        },
+      }),
+    );
+  });
+
+  it("returns plain text when response is not JSON", async () => {
+    performMatrixRequestMock.mockResolvedValue({
+      response: new Response("pong", {
+        status: 200,
+        headers: { "content-type": "text/plain" },
+      }),
+      text: "pong",
+      buffer: Buffer.from("pong", "utf8"),
+    });
+
+    const client = new MatrixAuthedHttpClient({
+      homeserver: "https://matrix.example.org",
+      accessToken: "token",
+    });
+    const result = await client.requestJson({
+      method: "GET",
+      endpoint: "/_lobi/client/v3/ping",
+      timeoutMs: 5000,
+    });
+
+    expect(result).toBe("pong");
+  });
+
+  it("returns raw buffers for media requests", async () => {
+    const payload = Buffer.from([1, 2, 3, 4]);
+    performMatrixRequestMock.mockResolvedValue({
+      response: new Response(payload, { status: 200 }),
+      text: payload.toString("utf8"),
+      buffer: payload,
+    });
+
+    const client = new MatrixAuthedHttpClient({
+      homeserver: "https://matrix.example.org",
+      accessToken: "token",
+    });
+    const result = await client.requestRaw({
+      method: "GET",
+      endpoint: "/_lobi/media/v3/download/example/id",
+      timeoutMs: 5000,
+    });
+
+    expect(result).toEqual(payload);
+  });
+
+  it("raises HTTP errors with status code metadata", async () => {
+    performMatrixRequestMock.mockResolvedValue({
+      response: new Response(JSON.stringify({ error: "forbidden" }), {
+        status: 403,
+        headers: { "content-type": "application/json" },
+      }),
+      text: JSON.stringify({ error: "forbidden" }),
+      buffer: Buffer.from(JSON.stringify({ error: "forbidden" }), "utf8"),
+    });
+
+    const client = new MatrixAuthedHttpClient({
+      homeserver: "https://matrix.example.org",
+      accessToken: "token",
+    });
+    await expect(
+      client.requestJson({
+        method: "GET",
+        endpoint: "/_lobi/client/v3/rooms",
+        timeoutMs: 5000,
+      }),
+    ).rejects.toMatchObject({
+      message: "forbidden",
+      statusCode: 403,
+    });
+  });
+});

package/src/matrix/sdk/http-client.ts

@@ -0,0 +1,87 @@
+import type { PinnedDispatcherPolicy } from "openclaw/plugin-sdk/infra-runtime";
+import type { SsrFPolicy } from "../../runtime-api.js";
+import { buildHttpError } from "./event-helpers.js";
+import { type HttpMethod, type QueryParams, performMatrixRequest } from "./transport.js";
+
+type MatrixAuthedHttpClientParams = {
+  homeserver: string;
+  accessToken: string;
+  ssrfPolicy?: SsrFPolicy;
+  dispatcherPolicy?: PinnedDispatcherPolicy;
+};
+
+export class MatrixAuthedHttpClient {
+  private readonly homeserver: string;
+  private readonly accessToken: string;
+  private readonly ssrfPolicy?: SsrFPolicy;
+  private readonly dispatcherPolicy?: PinnedDispatcherPolicy;
+
+  constructor(params: MatrixAuthedHttpClientParams) {
+    this.homeserver = params.homeserver;
+    this.accessToken = params.accessToken;
+    this.ssrfPolicy = params.ssrfPolicy;
+    this.dispatcherPolicy = params.dispatcherPolicy;
+  }
+
+  async requestJson(params: {
+    method: HttpMethod;
+    endpoint: string;
+    qs?: QueryParams;
+    body?: unknown;
+    timeoutMs: number;
+    allowAbsoluteEndpoint?: boolean;
+  }): Promise<unknown> {
+    const { response, text } = await performMatrixRequest({
+      homeserver: this.homeserver,
+      accessToken: this.accessToken,
+      method: params.method,
+      endpoint: params.endpoint,
+      qs: params.qs,
+      body: params.body,
+      timeoutMs: params.timeoutMs,
+      ssrfPolicy: this.ssrfPolicy,
+      dispatcherPolicy: this.dispatcherPolicy,
+      allowAbsoluteEndpoint: params.allowAbsoluteEndpoint,
+    });
+    if (!response.ok) {
+      throw buildHttpError(response.status, text);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      if (!text.trim()) {
+        return {};
+      }
+      return JSON.parse(text);
+    }
+    return text;
+  }
+
+  async requestRaw(params: {
+    method: HttpMethod;
+    endpoint: string;
+    qs?: QueryParams;
+    timeoutMs: number;
+    maxBytes?: number;
+    readIdleTimeoutMs?: number;
+    allowAbsoluteEndpoint?: boolean;
+  }): Promise<Buffer> {
+    const { response, buffer } = await performMatrixRequest({
+      homeserver: this.homeserver,
+      accessToken: this.accessToken,
+      method: params.method,
+      endpoint: params.endpoint,
+      qs: params.qs,
+      timeoutMs: params.timeoutMs,
+      raw: true,
+      maxBytes: params.maxBytes,
+      readIdleTimeoutMs: params.readIdleTimeoutMs,
+      ssrfPolicy: this.ssrfPolicy,
+      dispatcherPolicy: this.dispatcherPolicy,
+      allowAbsoluteEndpoint: params.allowAbsoluteEndpoint,
+    });
+    if (!response.ok) {
+      throw buildHttpError(response.status, buffer.toString("utf8"));
+    }
+    return buffer;
+  }
+}

package/src/matrix/sdk/idb-persistence-lock.ts

@@ -0,0 +1,51 @@
+import type { FileLockOptions } from "openclaw/plugin-sdk/infra-runtime";
+
+export const MATRIX_IDB_PERSIST_INTERVAL_MS = 60_000;
+
+const IDB_SNAPSHOT_LOCK_STALE_MS = 5 * 60_000;
+const IDB_SNAPSHOT_LOCK_RETRY_BASE = {
+  factor: 2,
+  minTimeout: 50,
+  maxTimeout: 5_000,
+  randomize: true,
+} satisfies Omit<FileLockOptions["retries"], "retries">;
+
+function computeRetryDelayMs(retries: FileLockOptions["retries"], attempt: number): number {
+  return Math.min(
+    retries.maxTimeout,
+    Math.max(retries.minTimeout, retries.minTimeout * retries.factor ** attempt),
+  );
+}
+
+export function computeMinimumRetryWindowMs(retries: FileLockOptions["retries"]): number {
+  let total = 0;
+  const attempts = Math.max(1, retries.retries + 1);
+  for (let attempt = 0; attempt < attempts - 1; attempt += 1) {
+    total += computeRetryDelayMs(retries, attempt);
+  }
+  return total;
+}
+
+function resolveRetriesForMinimumWindowMs(
+  retries: Omit<FileLockOptions["retries"], "retries">,
+  minimumWindowMs: number,
+): FileLockOptions["retries"] {
+  const resolved: FileLockOptions["retries"] = {
+    ...retries,
+    retries: 0,
+  };
+  while (computeMinimumRetryWindowMs(resolved) < minimumWindowMs) {
+    resolved.retries += 1;
+  }
+  return resolved;
+}
+
+export const MATRIX_IDB_SNAPSHOT_LOCK_OPTIONS: FileLockOptions = {
+  // Wait longer than one periodic persist interval so a concurrent restore
+  // or large snapshot dump finishes instead of forcing warn-and-continue.
+  retries: resolveRetriesForMinimumWindowMs(
+    IDB_SNAPSHOT_LOCK_RETRY_BASE,
+    MATRIX_IDB_PERSIST_INTERVAL_MS,
+  ),
+  stale: IDB_SNAPSHOT_LOCK_STALE_MS,
+};

package/src/matrix/sdk/idb-persistence.lock-order.test.ts

@@ -0,0 +1,108 @@
+import "fake-indexeddb/auto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  computeMinimumRetryWindowMs,
+  MATRIX_IDB_PERSIST_INTERVAL_MS,
+} from "./idb-persistence-lock.js";
+import { clearAllIndexedDbState, seedDatabase } from "./idb-persistence.test-helpers.js";
+
+const { withFileLockMock } = vi.hoisted(() => ({
+  withFileLockMock: vi.fn(
+    async <T>(_filePath: string, _options: unknown, fn: () => Promise<T>) => await fn(),
+  ),
+}));
+
+vi.mock("openclaw/plugin-sdk/infra-runtime", async () => {
+  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/infra-runtime")>(
+    "openclaw/plugin-sdk/infra-runtime",
+  );
+  return {
+    ...actual,
+    withFileLock: withFileLockMock,
+  };
+});
+
+let persistIdbToDisk: typeof import("./idb-persistence.js").persistIdbToDisk;
+let restoreIdbFromDisk: typeof import("./idb-persistence.js").restoreIdbFromDisk;
+type CapturedLockOptions =
+  typeof import("./idb-persistence-lock.js").MATRIX_IDB_SNAPSHOT_LOCK_OPTIONS;
+
+beforeAll(async () => {
+  ({ persistIdbToDisk, restoreIdbFromDisk } = await import("./idb-persistence.js"));
+});
+
+describe("Matrix IndexedDB persistence lock ordering", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "matrix-idb-lock-order-"));
+    withFileLockMock.mockReset();
+    withFileLockMock.mockImplementation(
+      async <T>(_filePath: string, _options: unknown, fn: () => Promise<T>) => await fn(),
+    );
+    await clearAllIndexedDbState();
+  });
+
+  afterEach(async () => {
+    await clearAllIndexedDbState();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("captures the snapshot after the file lock is acquired", async () => {
+    const snapshotPath = path.join(tmpDir, "crypto-idb-snapshot.json");
+    const dbName = "openclaw-matrix-test::matrix-sdk-crypto";
+    await seedDatabase({
+      name: dbName,
+      storeName: "sessions",
+      records: [{ key: "room-1", value: { session: "old-session" } }],
+    });
+
+    withFileLockMock.mockImplementationOnce(async (_filePath, _options, fn) => {
+      await seedDatabase({
+        name: dbName,
+        storeName: "sessions",
+        records: [{ key: "room-1", value: { session: "new-session" } }],
+      });
+      return await fn();
+    });
+
+    await persistIdbToDisk({ snapshotPath, databasePrefix: "openclaw-matrix-test" });
+
+    const data = JSON.parse(fs.readFileSync(snapshotPath, "utf8")) as Array<{
+      stores: Array<{
+        name: string;
+        records: Array<{ key: IDBValidKey; value: { session: string } }>;
+      }>;
+    }>;
+    const sessionsStore = data[0]?.stores.find((store) => store.name === "sessions");
+    expect(sessionsStore?.records).toEqual([{ key: "room-1", value: { session: "new-session" } }]);
+  });
+
+  it("waits at least one persist interval before timing out on snapshot lock contention", async () => {
+    const snapshotPath = path.join(tmpDir, "crypto-idb-snapshot.json");
+    const capturedOptions: CapturedLockOptions[] = [];
+
+    withFileLockMock.mockImplementationOnce(async (_filePath, options) => {
+      capturedOptions.push(options as CapturedLockOptions);
+      return 0;
+    });
+    await persistIdbToDisk({ snapshotPath, databasePrefix: "openclaw-matrix-test" });
+
+    withFileLockMock.mockImplementationOnce(async (_filePath, options) => {
+      capturedOptions.push(options as CapturedLockOptions);
+      return false;
+    });
+    await restoreIdbFromDisk(snapshotPath);
+
+    expect(capturedOptions).toHaveLength(2);
+    for (const options of capturedOptions) {
+      expect(computeMinimumRetryWindowMs(options.retries)).toBeGreaterThanOrEqual(
+        MATRIX_IDB_PERSIST_INTERVAL_MS,
+      );
+      expect(options.stale).toBe(5 * 60_000);
+    }
+  });
+});

package/src/matrix/sdk/idb-persistence.test-helpers.ts

@@ -0,0 +1,88 @@
+export async function clearAllIndexedDbState(): Promise<void> {
+  const databases = await indexedDB.databases();
+  await Promise.all(
+    databases
+      .map((entry) => entry.name)
+      .filter((name): name is string => Boolean(name))
+      .map(
+        (name) =>
+          new Promise<void>((resolve, reject) => {
+            const req = indexedDB.deleteDatabase(name);
+            req.addEventListener("success", () => resolve(), { once: true });
+            req.addEventListener("error", () => reject(req.error), { once: true });
+            req.addEventListener("blocked", () => resolve(), { once: true });
+          }),
+      ),
+  );
+}
+
+export async function seedDatabase(params: {
+  name: string;
+  version?: number;
+  storeName: string;
+  records: Array<{ key: IDBValidKey; value: unknown }>;
+}): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const req = indexedDB.open(params.name, params.version ?? 1);
+    req.addEventListener("upgradeneeded", () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(params.storeName)) {
+        db.createObjectStore(params.storeName);
+      }
+    });
+    req.addEventListener("success", () => {
+      const db = req.result;
+      const tx = db.transaction(params.storeName, "readwrite");
+      const store = tx.objectStore(params.storeName);
+      for (const record of params.records) {
+        store.put(record.value, record.key);
+      }
+      tx.addEventListener("complete", () => {
+        db.close();
+        resolve();
+      });
+      tx.addEventListener("error", () => reject(tx.error), { once: true });
+    });
+    req.addEventListener("error", () => reject(req.error), { once: true });
+  });
+}
+
+export async function readDatabaseRecords(params: {
+  name: string;
+  version?: number;
+  storeName: string;
+}): Promise<Array<{ key: IDBValidKey; value: unknown }>> {
+  return await new Promise((resolve, reject) => {
+    const req = indexedDB.open(params.name, params.version ?? 1);
+    req.addEventListener("success", () => {
+      const db = req.result;
+      const tx = db.transaction(params.storeName, "readonly");
+      const store = tx.objectStore(params.storeName);
+      const keysReq = store.getAllKeys();
+      const valuesReq = store.getAll();
+      let keys: IDBValidKey[] | null = null;
+      let values: unknown[] | null = null;
+
+      const maybeResolve = () => {
+        if (!keys || !values) {
+          return;
+        }
+        db.close();
+        const resolvedValues = values;
+        resolve(keys.map((key, index) => ({ key, value: resolvedValues[index] })));
+      };
+
+      keysReq.addEventListener("success", () => {
+        keys = keysReq.result;
+        maybeResolve();
+      });
+      valuesReq.addEventListener("success", () => {
+        values = valuesReq.result;
+        maybeResolve();
+      });
+      keysReq.addEventListener("error", () => reject(keysReq.error), { once: true });
+      valuesReq.addEventListener("error", () => reject(valuesReq.error), { once: true });
+    });
+    req.addEventListener("error", () => reject(req.error), { once: true });
+  });
+}

package/src/matrix/sdk/idb-persistence.test.ts

@@ -0,0 +1,149 @@
+import "fake-indexeddb/auto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  drainFileLockStateForTest,
+  resetFileLockStateForTest,
+} from "openclaw/plugin-sdk/infra-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { persistIdbToDisk, restoreIdbFromDisk } from "./idb-persistence.js";
+import {
+  clearAllIndexedDbState,
+  readDatabaseRecords,
+  seedDatabase,
+} from "./idb-persistence.test-helpers.js";
+import { LogService } from "./logger.js";
+
+describe("Matrix IndexedDB persistence", () => {
+  let tmpDir: string;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "matrix-idb-persist-"));
+    warnSpy = vi.spyOn(LogService, "warn").mockImplementation(() => {});
+    await clearAllIndexedDbState();
+  });
+
+  afterEach(async () => {
+    warnSpy.mockRestore();
+    await clearAllIndexedDbState();
+    resetFileLockStateForTest();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("persists and restores database contents for the selected prefix", async () => {
+    const snapshotPath = path.join(tmpDir, "crypto-idb-snapshot.json");
+    await seedDatabase({
+      name: "openclaw-matrix-test::matrix-sdk-crypto",
+      storeName: "sessions",
+      records: [{ key: "room-1", value: { session: "abc123" } }],
+    });
+    await seedDatabase({
+      name: "other-prefix::matrix-sdk-crypto",
+      storeName: "sessions",
+      records: [{ key: "room-2", value: { session: "should-not-restore" } }],
+    });
+
+    await persistIdbToDisk({
+      snapshotPath,
+      databasePrefix: "openclaw-matrix-test",
+    });
+    expect(fs.existsSync(snapshotPath)).toBe(true);
+
+    const mode = fs.statSync(snapshotPath).mode & 0o777;
+    expect(mode).toBe(0o600);
+
+    await clearAllIndexedDbState();
+
+    const restored = await restoreIdbFromDisk(snapshotPath);
+    expect(restored).toBe(true);
+
+    const restoredRecords = await readDatabaseRecords({
+      name: "openclaw-matrix-test::matrix-sdk-crypto",
+      storeName: "sessions",
+    });
+    expect(restoredRecords).toEqual([{ key: "room-1", value: { session: "abc123" } }]);
+
+    const dbs = await indexedDB.databases();
+    expect(dbs.some((entry) => entry.name === "other-prefix::matrix-sdk-crypto")).toBe(false);
+  });
+
+  it("returns false and logs a warning for malformed snapshots", async () => {
+    const snapshotPath = path.join(tmpDir, "bad-snapshot.json");
+    fs.writeFileSync(snapshotPath, JSON.stringify([{ nope: true }]), "utf8");
+
+    const restored = await restoreIdbFromDisk(snapshotPath);
+    expect(restored).toBe(false);
+    expect(warnSpy).toHaveBeenCalledWith(
+      "IdbPersistence",
+      expect.stringContaining(`Failed to restore IndexedDB snapshot from ${snapshotPath}:`),
+      expect.any(Error),
+    );
+  });
+
+  it("returns false for empty snapshot payloads without restoring databases", async () => {
+    const snapshotPath = path.join(tmpDir, "empty-snapshot.json");
+    fs.writeFileSync(snapshotPath, JSON.stringify([]), "utf8");
+
+    const restored = await restoreIdbFromDisk(snapshotPath);
+    expect(restored).toBe(false);
+
+    const dbs = await indexedDB.databases();
+    expect(dbs).toEqual([]);
+  });
+
+  it("serializes concurrent persist operations via file lock", async () => {
+    const snapshotPath = path.join(tmpDir, "concurrent-persist.json");
+    await seedDatabase({
+      name: "openclaw-matrix-test::matrix-sdk-crypto",
+      storeName: "sessions",
+      records: [{ key: "room-1", value: { session: "abc123" } }],
+    });
+
+    await Promise.all([
+      persistIdbToDisk({ snapshotPath, databasePrefix: "openclaw-matrix-test" }),
+      persistIdbToDisk({ snapshotPath, databasePrefix: "openclaw-matrix-test" }),
+    ]);
+
+    expect(fs.existsSync(snapshotPath)).toBe(true);
+
+    const data = JSON.parse(fs.readFileSync(snapshotPath, "utf8"));
+    expect(Array.isArray(data)).toBe(true);
+    expect(data.length).toBe(1);
+  });
+
+  it("releases lock after persist completes", async () => {
+    const snapshotPath = path.join(tmpDir, "lock-release.json");
+    await seedDatabase({
+      name: "openclaw-matrix-test::matrix-sdk-crypto",
+      storeName: "sessions",
+      records: [{ key: "room-1", value: { session: "abc123" } }],
+    });
+
+    await persistIdbToDisk({ snapshotPath, databasePrefix: "openclaw-matrix-test" });
+
+    const lockPath = `${snapshotPath}.lock`;
+    expect(fs.existsSync(lockPath)).toBe(false);
+    await drainFileLockStateForTest();
+  });
+
+  it("releases lock after restore completes", async () => {
+    const snapshotPath = path.join(tmpDir, "lock-release-restore.json");
+    await seedDatabase({
+      name: "openclaw-matrix-test::matrix-sdk-crypto",
+      storeName: "sessions",
+      records: [{ key: "room-1", value: { session: "abc123" } }],
+    });
+
+    await persistIdbToDisk({ snapshotPath, databasePrefix: "openclaw-matrix-test" });
+    await clearAllIndexedDbState();
+    await drainFileLockStateForTest();
+
+    await restoreIdbFromDisk(snapshotPath);
+
+    const lockPath = `${snapshotPath}.lock`;
+    expect(fs.existsSync(lockPath)).toBe(false);
+    await drainFileLockStateForTest();
+  });
+});