@openclaw/matrix 2026.7.2-beta.7 → 2026.8.1-beta.2

package/dist/doctor-contract-api.js

@@ -1,23 +1,20 @@
-import { a as resolveMatrixDefaultOrOnlyAccountId, n as requiresExplicitMatrixDefaultAccount } from "./account-selection-kqquRzCf.js";
-import { t as isRecord$1 } from "./record-shared-CWWx6fvI.js";
+import { a as resolveMatrixDefaultOrOnlyAccountId, n as requiresExplicitMatrixDefaultAccount } from "./account-selection-CWuhuFn1.js";
+import { i as normalizeMatrixStoredCredentials, n as isMatrixCredentialRevocation, r as matrixCredentialsStoreKey, t as MATRIX_CREDENTIALS_NAMESPACE } from "./credentials-state-B3cuUFwZ.js";
 import { r as resolveMatrixCredentialsDir } from "./storage-paths-gUmSydsW.js";
-import { a as isMatrixCredentialRevocation, c as normalizeMatrixStoredCredentials, s as matrixCredentialsStoreKey, t as MATRIX_CREDENTIALS_NAMESPACE } from "./credentials-read-DVmFCm7X.js";
-import { n as normalizeCompatibilityConfig, t as legacyConfigRules } from "./doctor-contract-BMSJkkAE.js";
-import { C as readLegacyMatrixRecoveryKeyState, O as writeMatrixIdbSnapshotJsonToStore, T as readMatrixIdbSnapshotJsonFromStore, a as openMatrixStorageMetaStoreOptions, b as openMatrixRecoveryKeyStoreOptions, f as MATRIX_IDB_SNAPSHOT_FILENAME, g as hasMatrixRecoveryKeyStateInStore, h as hasMatrixLegacyCryptoMigrationStateInStore, i as normalizeMatrixStorageMetadata, j as writeMatrixRecoveryKeyStateToStore, k as writeMatrixLegacyCryptoMigrationStateToStore, m as MATRIX_RECOVERY_KEY_FILENAME, n as hasMatrixStorageMetaStateInStore, p as MATRIX_LEGACY_CRYPTO_MIGRATION_FILENAME, u as writeMatrixStorageMetaStateToStore, v as openMatrixIdbSnapshotStoreOptions, x as readLegacyMatrixLegacyCryptoMigrationState, y as openMatrixLegacyCryptoMigrationStoreOptions } from "./storage-BvAkgzvT.js";
-import { a as readLegacyMatrixSyncCacheState, i as openMatrixSyncCacheStoreOptions, o as writeMatrixSyncCacheStateToStore, r as hasMatrixSyncCacheStateInStore } from "./file-sync-store-DiiFsayX.js";
+import { n as normalizeCompatibilityConfig, t as legacyConfigRules } from "./doctor-contract-DEt4O4Zt.js";
+import { C as readLegacyMatrixRecoveryKeyState, O as writeMatrixIdbSnapshotJsonToStore, T as readMatrixIdbSnapshotJsonFromStore, a as openMatrixStorageMetaStoreOptions, b as openMatrixRecoveryKeyStoreOptions, f as MATRIX_IDB_SNAPSHOT_FILENAME, g as hasMatrixRecoveryKeyStateInStore, h as hasMatrixLegacyCryptoMigrationStateInStore, i as normalizeMatrixStorageMetadata, j as writeMatrixRecoveryKeyStateToStore, k as writeMatrixLegacyCryptoMigrationStateToStore, m as MATRIX_RECOVERY_KEY_FILENAME, n as hasMatrixStorageMetaStateInStore, p as MATRIX_LEGACY_CRYPTO_MIGRATION_FILENAME, u as writeMatrixStorageMetaStateToStore, v as openMatrixIdbSnapshotStoreOptions, x as readLegacyMatrixLegacyCryptoMigrationState, y as openMatrixLegacyCryptoMigrationStoreOptions } from "./storage-BsGuHngK.js";
+import { a as readLegacyMatrixSyncCacheState, i as openMatrixSyncCacheStoreOptions, o as writeMatrixSyncCacheStateToStore, r as hasMatrixSyncCacheStateInStore } from "./file-sync-store-DjskBX2o.js";
 import { n as MATRIX_IDB_SNAPSHOT_LOCK_OPTIONS } from "./idb-persistence-lock-DAJ49nZX.js";
-import { r as readLegacyMatrixIdbSnapshotStateUnlocked, t as isValidMatrixIdbSnapshotJson } from "./idb-persistence-B6x7dMsF.js";
-import { a as resolveMatrixInboundDedupeStateNamespace, n as MATRIX_INBOUND_DEDUPE_TTL_MS, r as buildMatrixInboundDedupeEventKey } from "./inbound-dedupe-CaBLblef.js";
+import { r as readLegacyMatrixIdbSnapshotStateUnlocked, t as isValidMatrixIdbSnapshotJson } from "./idb-persistence-BM0P27Zg.js";
 import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { archiveLegacyStateSource } from "openclaw/plugin-sdk/runtime-doctor";
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
+import { archiveLegacyStateSource } from "openclaw/plugin-sdk/runtime-doctor-migrations";
 import fs from "node:fs";
 import fs$1 from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
 import { withFileLock } from "openclaw/plugin-sdk/file-lock";
-import { createPersistentDedupeImportEntry } from "openclaw/plugin-sdk/persistent-dedupe";
 //#region extensions/matrix/src/matrix/crypto-snapshot-doctor.ts
 async function migrateLegacyMatrixIdbSnapshot(params) {
 	const snapshotPath = path.join(params.storageRootDir, MATRIX_IDB_SNAPSHOT_FILENAME);
@@ -101,21 +98,55 @@ async function archiveLegacyMatrixIdbSnapshot(params) {
 //#endregion
 //#region extensions/matrix/src/matrix/monitor/inbound-dedupe-migration.ts
 const LEGACY_SQLITE_NAMESPACE = "inbound-dedupe";
-const LEGACY_SQLITE_MAX_ENTRIES = 2e4;
 const LEGACY_MARKERS_NAMESPACE = "inbound-dedupe-migrations";
-const LEGACY_MARKERS_MAX_ENTRIES = 1e3;
 const LEGACY_JSON_VERSION = 1;
+const MATRIX_PLUGIN_ID = "matrix";
+const MIGRATION_COMPLETION_NAMESPACE = "inbound-dedupe-migration-state";
+const MIGRATION_COMPLETION_KEY = "sqlite-json-to-claimable-v1";
+const STATE_DATABASE_RELATIVE_PATH = path.join("state", "openclaw.sqlite");
 const STORAGE_META_FILENAME = "storage-meta.json";
 const MATRIX_LEGACY_INBOUND_DEDUPE_FILENAME = "inbound-dedupe.json";
+function openMatrixInboundDedupeMigrationCompletionStore(context, env) {
+	return context.openPluginStateKeyedStore({
+		namespace: MIGRATION_COMPLETION_NAMESPACE,
+		maxEntries: 4,
+		overflowPolicy: "reject-new",
+		env
+	});
+}
+async function hasCompletedMatrixInboundDedupeMigration(context, env) {
+	const marker = await openMatrixInboundDedupeMigrationCompletionStore(context, env).lookup(MIGRATION_COMPLETION_KEY);
+	return isRecord(marker) && marker.version === 1 && typeof marker.completedAt === "number" && Number.isFinite(marker.completedAt) && marker.completedAt >= 0;
+}
+async function recordMatrixInboundDedupeMigrationCompletion(context, env) {
+	await openMatrixInboundDedupeMigrationCompletionStore(context, env).register(MIGRATION_COMPLETION_KEY, {
+		version: 1,
+		completedAt: Date.now()
+	});
+}
+/**
+* Reserves the durable completion row before any legacy source is changed.
+* The invalid timestamp keeps detection active after an interrupted run, while
+* updating this same key after retirement remains possible at plugin capacity.
+*/
+async function reserveMatrixInboundDedupeMigrationCompletion(context, env) {
+	await openMatrixInboundDedupeMigrationCompletionStore(context, env).register(MIGRATION_COMPLETION_KEY, {
+		version: 1,
+		completedAt: -1
+	});
+}
 async function collectMatrixInboundDedupeSources(stateDir) {
 	const matrixRoot = path.join(stateDir, "matrix");
 	const sqliteRoots = /* @__PURE__ */ new Set();
 	const jsonRoots = /* @__PURE__ */ new Set();
-	async function visit(dir) {
+	const warnings = [];
+	async function visit(dir, allowMissing = false) {
 		let entries;
 		try {
 			entries = await fs$1.readdir(dir, { withFileTypes: true });
-		} catch {
+		} catch (err) {
+			if (allowMissing && err.code === "ENOENT") return;
+			warnings.push(`Failed scanning Matrix inbound dedupe sources under ${dir}: ${String(err)}`);
 			return;
 		}
 		for (const entry of entries) {
@@ -128,40 +159,41 @@ async function collectMatrixInboundDedupeSources(stateDir) {
 			if (entry.isDirectory()) await visit(entryPath);
 		}
 	}
-	await visit(matrixRoot);
+	await visit(matrixRoot, true);
 	const matrixRootResolved = path.resolve(matrixRoot);
 	const isAccountRoot = (root) => path.resolve(root) !== matrixRootResolved;
-	return {
+	const roots = {
 		sqliteRoots: [...sqliteRoots].filter(isAccountRoot).toSorted(),
 		jsonRoots: [...jsonRoots].filter(isAccountRoot).toSorted()
 	};
+	return warnings.length === 0 ? {
+		status: "complete",
+		...roots
+	} : {
+		status: "incomplete",
+		...roots,
+		warnings
+	};
 }
-function openLegacySqliteStore(io, storageRootDir) {
-	return io.context.openPluginStateKeyedStore({
-		namespace: LEGACY_SQLITE_NAMESPACE,
-		maxEntries: LEGACY_SQLITE_MAX_ENTRIES,
-		env: {
-			...io.env,
-			OPENCLAW_STATE_DIR: storageRootDir
-		}
-	});
+function selectLegacySqliteRows(db) {
+	if (!db.prepare(`SELECT 1 AS present
+       FROM sqlite_master
+       WHERE type = 'table' AND name = 'plugin_state_entries'`).get()) return [];
+	return db.prepare(`SELECT namespace, entry_key, value_json, expires_at
+       FROM plugin_state_entries
+       WHERE plugin_id = ? AND namespace IN (?, ?)
+       ORDER BY namespace ASC, created_at ASC, entry_key ASC`).all(MATRIX_PLUGIN_ID, LEGACY_SQLITE_NAMESPACE, LEGACY_MARKERS_NAMESPACE);
 }
-function openLegacyMarkersStore(io, storageRootDir) {
-	return io.context.openPluginStateKeyedStore({
-		namespace: LEGACY_MARKERS_NAMESPACE,
-		maxEntries: LEGACY_MARKERS_MAX_ENTRIES,
-		env: {
-			...io.env,
-			OPENCLAW_STATE_DIR: storageRootDir
-		}
-	});
+function isLegacySqliteRowExpired(row, now) {
+	if (typeof row.expires_at === "bigint") return row.expires_at <= BigInt(now);
+	return row.expires_at !== null && row.expires_at <= now;
 }
 function normalizeLegacyTimestamp(raw) {
 	if (typeof raw !== "number" || !Number.isFinite(raw)) return null;
 	return Math.max(0, Math.floor(raw));
 }
 function parseLegacySqliteRow(row) {
-	const value = isRecord$1(row.value) ? row.value : {};
+	const value = isRecord(row.value) ? row.value : {};
 	const roomId = typeof value.roomId === "string" ? value.roomId.trim() : "";
 	const eventId = typeof value.eventId === "string" ? value.eventId.trim() : "";
 	const ts = normalizeLegacyTimestamp(value.ts);
@@ -177,24 +209,63 @@ function parseLegacySqliteRow(row) {
 		ts
 	};
 }
-/** Reads one storage root's legacy SQLite dedupe rows; throws on store errors. */
-async function readLegacyInboundDedupeSqliteSource(io, storageRootDir) {
-	const rows = await openLegacySqliteStore(io, storageRootDir).entries();
-	const markerRows = await openLegacyMarkersStore(io, storageRootDir).entries();
-	const markers = [];
-	for (const row of rows) {
-		const marker = parseLegacySqliteRow(row);
-		if (marker) markers.push(marker);
+/**
+* Reads one storage root's legacy SQLite dedupe rows without opening it through
+* the current state runtime. Historical per-account databases can predate the
+* current core schema, and detection must not upgrade them merely to inspect
+* these retired plugin-state namespaces.
+*/
+async function readLegacyInboundDedupeSqliteSource(storageRootDir) {
+	const { openNodeSqliteDatabase } = await import("openclaw/plugin-sdk/sqlite-runtime");
+	const db = openNodeSqliteDatabase(path.join(storageRootDir, STATE_DATABASE_RELATIVE_PATH), { readOnly: true });
+	try {
+		const rows = selectLegacySqliteRows(db);
+		const markers = [];
+		const now = Date.now();
+		for (const row of rows) {
+			if (isLegacySqliteRowExpired(row, now)) continue;
+			const value = JSON.parse(row.value_json);
+			if (row.namespace !== LEGACY_SQLITE_NAMESPACE) continue;
+			const marker = parseLegacySqliteRow({
+				key: row.entry_key,
+				value
+			});
+			if (marker) markers.push(marker);
+		}
+		return {
+			markers,
+			legacyRowCount: rows.length
+		};
+	} finally {
+		db.close();
+	}
+}
+/** Deletes only the two retired Matrix namespaces after a successful import. */
+async function retireLegacyInboundDedupeSqliteRows(storageRootDir) {
+	const { openNodeSqliteDatabase, runSqliteImmediateTransactionSync } = await import("openclaw/plugin-sdk/sqlite-runtime");
+	const db = openNodeSqliteDatabase(path.join(storageRootDir, STATE_DATABASE_RELATIVE_PATH));
+	try {
+		if (selectLegacySqliteRows(db).length === 0) return;
+		runSqliteImmediateTransactionSync(db, () => {
+			if (selectLegacySqliteRows(db).length === 0) return;
+			db.prepare(`DELETE FROM plugin_state_entries
+         WHERE plugin_id = ? AND namespace IN (?, ?)`).run(MATRIX_PLUGIN_ID, LEGACY_SQLITE_NAMESPACE, LEGACY_MARKERS_NAMESPACE);
+		});
+	} finally {
+		db.close();
 	}
-	return {
-		markers,
-		legacyRowCount: rows.length + markerRows.length
-	};
 }
-/** Clears one storage root's retired legacy dedupe namespaces after import. */
-async function retireLegacyInboundDedupeSqliteRows(io, storageRootDir) {
-	await openLegacySqliteStore(io, storageRootDir).clear();
-	await openLegacyMarkersStore(io, storageRootDir).clear();
+async function verifyMatrixInboundDedupeSourcesRetired(stateDir) {
+	const warnings = [];
+	const remaining = await collectMatrixInboundDedupeSources(stateDir);
+	if (remaining.status === "incomplete") warnings.push(...remaining.warnings);
+	for (const storageRootDir of remaining.sqliteRoots) try {
+		if ((await readLegacyInboundDedupeSqliteSource(storageRootDir)).legacyRowCount > 0) warnings.push(`Matrix inbound dedupe rows remain after retirement for ${storageRootDir}`);
+	} catch (err) {
+		warnings.push(`Failed verifying retired Matrix inbound dedupe rows for ${storageRootDir}: ${String(err)}`);
+	}
+	for (const storageRootDir of remaining.jsonRoots) warnings.push(`Matrix inbound dedupe JSON remains after retirement for ${storageRootDir}`);
+	return warnings;
 }
 async function resolveJsonRootAccountId(storageRootDir) {
 	for (const filename of [STORAGE_META_FILENAME, `${STORAGE_META_FILENAME}.migrated`]) try {
@@ -217,11 +288,11 @@ async function readLegacyInboundDedupeJsonSource(storageRootDir) {
 	} catch {
 		return null;
 	}
-	if (!isRecord$1(parsed) || parsed.version !== LEGACY_JSON_VERSION || !Array.isArray(parsed.entries)) return null;
+	if (!isRecord(parsed) || parsed.version !== LEGACY_JSON_VERSION || !Array.isArray(parsed.entries)) return null;
 	const accountId = await resolveJsonRootAccountId(storageRootDir);
 	const markers = [];
 	for (const entry of parsed.entries) {
-		if (!isRecord$1(entry) || typeof entry.key !== "string") continue;
+		if (!isRecord(entry) || typeof entry.key !== "string") continue;
 		const separator = entry.key.indexOf("|");
 		if (separator <= 0) continue;
 		const roomId = entry.key.slice(0, separator).trim();
@@ -239,14 +310,16 @@ async function readLegacyInboundDedupeJsonSource(storageRootDir) {
 }
 /**
 * Imports the globally newest legacy markers into the claimable-dedupe store.
-* Never exceeds capacity: eviction is by row creation time, so letting fresh
-* imports overflow the namespace would evict the newer rows the runtime
-* committed since the upgrade. Throws on store errors so the caller keeps the
-* legacy sources for the next doctor attempt.
+* Never exceeds capacity, never replaces a post-upgrade destination row, and
+* preserves source timestamps because eviction is ordered by row creation
+* time. Throws on import or verification errors so the caller keeps the legacy
+* sources for the next doctor attempt.
 */
 async function importNewestInboundDedupeMarkers(params) {
+	const { createPersistentDedupeImportEntry } = await import("openclaw/plugin-sdk/persistent-dedupe");
+	const { buildMatrixInboundDedupeEventKey, MATRIX_INBOUND_DEDUPE_STATE_MAX_ENTRIES, MATRIX_INBOUND_DEDUPE_TTL_MS, resolveMatrixInboundDedupeStateNamespace } = await import("./inbound-dedupe-RvSLqdsz.js");
 	const now = params.now ?? Date.now();
-	const stateMaxEntries = params.stateMaxEntries ?? 2e4;
+	const stateMaxEntries = params.stateMaxEntries ?? MATRIX_INBOUND_DEDUPE_STATE_MAX_ENTRIES;
 	const newestByKey = /* @__PURE__ */ new Map();
 	for (const marker of params.markers) {
 		const key = buildMatrixInboundDedupeEventKey(marker);
@@ -264,24 +337,47 @@ async function importNewestInboundDedupeMarkers(params) {
 		defaultTtlMs: MATRIX_INBOUND_DEDUPE_TTL_MS,
 		env: params.io.env
 	});
-	let capacity = Math.max(0, stateMaxEntries - (await store.entries()).length);
-	let imported = 0;
-	for (const marker of markers) {
-		if (capacity <= 0) break;
+	const existingEntries = await store.entries();
+	const existingKeys = new Set(existingEntries.map((entry) => entry.key));
+	const missingEntries = markers.flatMap((marker) => {
 		const remainingTtlMs = MATRIX_INBOUND_DEDUPE_TTL_MS - (now - marker.ts);
-		if (remainingTtlMs <= 0) continue;
+		if (remainingTtlMs <= 0) return [];
 		const entry = createPersistentDedupeImportEntry({
 			key: marker.key,
 			seenAt: marker.ts,
 			ttlMs: Math.max(1, Math.floor(remainingTtlMs))
 		});
-		if (await store.registerIfAbsent(entry.key, entry.value, { ttlMs: entry.ttlMs ?? 2592e6 })) {
-			imported += 1;
-			capacity -= 1;
-		}
+		return existingKeys.has(entry.key) ? [] : [{
+			marker,
+			entry
+		}];
+	});
+	const namespaceCapacity = Math.max(0, stateMaxEntries - existingEntries.length);
+	const pluginCapacity = missingEntries.length > 0 ? params.io.context.getPluginStateCapacity?.() : void 0;
+	if (missingEntries.length > 0 && !pluginCapacity) throw new Error("plugin-wide Matrix inbound dedupe import capacity is unavailable");
+	const pluginRemainingCapacity = pluginCapacity ? Math.max(0, pluginCapacity.maxEntries - pluginCapacity.liveEntries) : namespaceCapacity;
+	const capacity = Math.min(namespaceCapacity, pluginRemainingCapacity);
+	const selectedEntries = missingEntries.slice(0, capacity);
+	if (selectedEntries.length > 0) {
+		const importEntries = params.io.context.importPluginStateEntries;
+		if (!importEntries) throw new Error("retention-aware Matrix inbound dedupe import is unavailable");
+		importEntries({
+			namespace: resolveMatrixInboundDedupeStateNamespace(),
+			maxEntries: stateMaxEntries,
+			defaultTtlMs: MATRIX_INBOUND_DEDUPE_TTL_MS,
+			env: params.io.env
+		}, selectedEntries.map(({ marker, entry }) => ({
+			key: entry.key,
+			value: entry.value,
+			createdAt: marker.ts,
+			...entry.ttlMs != null ? { ttlMs: entry.ttlMs } : {}
+		})));
+		const importedKeys = new Set((await store.entries()).map((entry) => entry.key));
+		const missingKey = selectedEntries.find(({ entry }) => !importedKeys.has(entry.key))?.entry.key;
+		if (missingKey) throw new Error(`retention-aware Matrix inbound dedupe import did not persist ${missingKey}`);
 	}
 	return {
-		imported,
+		imported: selectedEntries.length,
 		total: markers.length
 	};
 }
@@ -444,22 +540,7 @@ const stateMigrations = [
 		id: "matrix-inbound-dedupe-to-claimable-dedupe",
 		label: "Matrix inbound dedupe markers",
 		async detectLegacyState(params) {
-			const io = {
-				context: params.context,
-				env: params.env
-			};
-			const preview = [];
-			const sources = await collectMatrixInboundDedupeSources(params.stateDir);
-			for (const storageRootDir of sources.sqliteRoots) {
-				try {
-					if ((await readLegacyInboundDedupeSqliteSource(io, storageRootDir)).legacyRowCount === 0) continue;
-				} catch {
-					continue;
-				}
-				preview.push(`Matrix inbound dedupe rows can migrate to the claimable dedupe store: ${storageRootDir}`);
-			}
-			for (const storageRootDir of sources.jsonRoots) preview.push(`Matrix inbound dedupe JSON can migrate to the claimable dedupe store: ${path.join(storageRootDir, MATRIX_LEGACY_INBOUND_DEDUPE_FILENAME)}`);
-			return preview.length > 0 ? { preview } : null;
+			return await hasCompletedMatrixInboundDedupeMigration(params.context, params.env) ? null : { preview: ["Matrix inbound dedupe legacy sources need a one-time migration scan"] };
 		},
 		async migrateLegacyState(params) {
 			const io = {
@@ -468,11 +549,38 @@ const stateMigrations = [
 			};
 			const changes = [];
 			const warnings = [];
+			if (await hasCompletedMatrixInboundDedupeMigration(params.context, params.env)) return {
+				changes,
+				warnings
+			};
+			try {
+				await reserveMatrixInboundDedupeMigrationCompletion(params.context, params.env);
+			} catch (err) {
+				warnings.push(`Failed reserving Matrix inbound dedupe migration completion: ${String(err)}; left legacy sources in place`);
+				return {
+					changes,
+					warnings
+				};
+			}
 			const sources = await collectMatrixInboundDedupeSources(params.stateDir);
+			if (sources.status === "incomplete") warnings.push(...sources.warnings);
+			const recordCompletionIfClean = async (verifyRetirement = false) => {
+				if (warnings.length > 0) return;
+				if (verifyRetirement) {
+					warnings.push(...await verifyMatrixInboundDedupeSourcesRetired(params.stateDir));
+					if (warnings.length > 0) return;
+				}
+				try {
+					await recordMatrixInboundDedupeMigrationCompletion(params.context, params.env);
+					if (sources.sqliteRoots.length + sources.jsonRoots.length > 0) changes.push(`Recorded Matrix inbound dedupe migration completion (${sources.sqliteRoots.length} SQLite roots, ${sources.jsonRoots.length} JSON roots scanned)`);
+				} catch (err) {
+					warnings.push(`Failed recording Matrix inbound dedupe migration completion: ${String(err)}`);
+				}
+			};
 			const gathered = [];
 			const sqliteRootsToRetire = [];
 			for (const storageRootDir of sources.sqliteRoots) try {
-				const source = await readLegacyInboundDedupeSqliteSource(io, storageRootDir);
+				const source = await readLegacyInboundDedupeSqliteSource(storageRootDir);
 				if (source.legacyRowCount === 0) continue;
 				gathered.push(...source.markers);
 				sqliteRootsToRetire.push(storageRootDir);
@@ -488,10 +596,13 @@ const stateMigrations = [
 			} catch (err) {
 				warnings.push(`Failed reading Matrix inbound dedupe JSON for ${storageRootDir}: ${String(err)}; left legacy file in place`);
 			}
-			if (sqliteRootsToRetire.length + jsonRootsToRetire.length === 0) return {
-				changes,
-				warnings
-			};
+			if (sqliteRootsToRetire.length + jsonRootsToRetire.length === 0) {
+				await recordCompletionIfClean();
+				return {
+					changes,
+					warnings
+				};
+			}
 			try {
 				const result = await importNewestInboundDedupeMarkers({
 					io,
@@ -506,7 +617,7 @@ const stateMigrations = [
 				};
 			}
 			for (const storageRootDir of sqliteRootsToRetire) try {
-				await retireLegacyInboundDedupeSqliteRows(io, storageRootDir);
+				await retireLegacyInboundDedupeSqliteRows(storageRootDir);
 				changes.push(`Retired Matrix inbound dedupe rows for ${storageRootDir}`);
 			} catch (err) {
 				warnings.push(`Failed retiring Matrix inbound dedupe rows for ${storageRootDir}: ${String(err)}`);
@@ -518,6 +629,7 @@ const stateMigrations = [
 				changes,
 				warnings
 			});
+			await recordCompletionIfClean(true);
 			return {
 				changes,
 				warnings

package/dist/{draft-stream-CtvOXq0Z.js → draft-stream-BRi7PRRS.js}

@@ -1,5 +1,5 @@
-import { _ as MsgType, a as sendSingleTextMessageMatrix, t as editMessageMatrix, y as prepareMatrixSingleText } from "./send-BldGYG8g.js";
-import { createDraftStreamLoop } from "openclaw/plugin-sdk/channel-outbound";
+import { E as MsgType, a as sendSingleTextMessageMatrix, l as prepareMatrixSingleText, t as editMessageMatrix } from "./send-ZDLU4JTk.js";
+import { createFinalizableDraftStreamControlsForState } from "openclaw/plugin-sdk/channel-outbound";
 //#region extensions/matrix/src/matrix/draft-stream.ts
 const DEFAULT_THROTTLE_MS = 1e3;
 function resolveDraftPreviewOptions(mode) {
@@ -19,22 +19,26 @@ function createMatrixDraftStream(params) {
 	let currentEventId;
 	let lastSentText = "";
 	let lastSentContent = "";
-	let stopped = false;
+	const streamState = {
+		stopped: false,
+		final: false
+	};
 	let sendFailed = false;
 	let finalizeInPlaceBlocked = false;
 	let liveFinalized = false;
 	let replyToId = params.replyToId;
 	const sendOrEdit = async (text) => {
 		const trimmed = text.trimEnd();
-		if (!trimmed) return false;
+		if (!trimmed.trim()) return false;
 		const preparedText = prepareMatrixSingleText(trimmed, {
 			cfg,
-			accountId
+			accountId,
+			preserveWhitespace: true
 		});
 		if (!preparedText.fitsInSingleEvent) {
 			finalizeInPlaceBlocked = true;
 			if (!currentEventId) sendFailed = true;
-			stopped = true;
+			streamState.stopped = true;
 			log?.(`draft-stream: preview exceeded single-event limit (${preparedText.convertedText.length} > ${preparedText.singleEventLimit})`);
 			return false;
 		}
@@ -73,13 +77,13 @@ function createMatrixDraftStream(params) {
 			log?.(`draft-stream: send/edit failed: ${String(err)}`);
 			if (err instanceof Error && err.message.startsWith("Matrix single-message text exceeds limit")) finalizeInPlaceBlocked = true;
 			if (!currentEventId) sendFailed = true;
-			stopped = true;
+			streamState.stopped = true;
 			return false;
 		}
 	};
-	const loop = createDraftStreamLoop({
+	const { loop, update, stop: stopDraft, discardPending } = createFinalizableDraftStreamControlsForState({
 		throttleMs: DEFAULT_THROTTLE_MS,
-		isStopped: () => stopped,
+		state: streamState,
 		sendOrEditStreamMessage: sendOrEdit
 	});
 	log?.(`draft-stream: ready (throttleMs=${DEFAULT_THROTTLE_MS})`);
@@ -107,21 +111,16 @@ function createMatrixDraftStream(params) {
 		return true;
 	};
 	const stop = async () => {
-		await loop.flush();
-		stopped = true;
+		await stopDraft();
 		return currentEventId;
 	};
-	const discardPending = async () => {
-		stopped = true;
-		loop.stop();
-		await loop.waitForInFlight();
-	};
 	const reset = () => {
 		replyToId = params.preserveReplyId ? params.replyToId : void 0;
 		currentEventId = void 0;
 		lastSentText = "";
 		lastSentContent = "";
-		stopped = false;
+		streamState.stopped = false;
+		streamState.final = false;
 		sendFailed = false;
 		finalizeInPlaceBlocked = false;
 		liveFinalized = false;
@@ -129,10 +128,7 @@ function createMatrixDraftStream(params) {
 		loop.resetThrottleWindow();
 	};
 	return {
-		update: (text) => {
-			if (stopped) return;
-			loop.update(text);
-		},
+		update,
 		flush: loop.flush,
 		stop,
 		discardPending,
@@ -140,9 +136,10 @@ function createMatrixDraftStream(params) {
 		reset,
 		eventId: () => currentEventId,
 		content: () => lastSentContent || void 0,
-		matchesPreparedText: (text) => prepareMatrixSingleText(text, {
+		matchesPreparedText: (text) => prepareMatrixSingleText(text.trimEnd(), {
 			cfg,
-			accountId
+			accountId,
+			preserveWhitespace: true
 		}).trimmedText === lastSentText,
 		mustDeliverFinalNormally: () => sendFailed || finalizeInPlaceBlocked
 	};

package/dist/{encryption-guidance-CbEFe38F.js → encryption-guidance-DmLY8NiO.js}

@@ -1,4 +1,4 @@
-import { a as resolveMatrixDefaultOrOnlyAccountId } from "./account-selection-kqquRzCf.js";
+import { a as resolveMatrixDefaultOrOnlyAccountId } from "./account-selection-CWuhuFn1.js";
 import { t as resolveMatrixConfigFieldPath } from "./config-paths-CnREYb1Y.js";
 import { normalizeOptionalAccountId } from "openclaw/plugin-sdk/account-id";
 //#region extensions/matrix/src/matrix/encryption-guidance.ts

package/dist/{env-auth-CQsYbz-p.js → env-auth-MVS-Vv41.js}

@@ -1,8 +1,9 @@
-import { t as getMatrixScopedEnvVarNames } from "./env-vars-B0NxQnPk.js";
+import { t as getMatrixScopedEnvVarNames } from "./env-vars-dGqak9dN.js";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 //#region extensions/matrix/src/matrix/client/env-auth.ts
 function cleanEnv(value) {
-	return typeof value === "string" ? value.trim() : "";
+	return normalizeOptionalString(value) ?? "";
 }
 function resolveGlobalMatrixEnvConfig(env) {
 	return {
@@ -60,4 +61,4 @@ function resolveMatrixEnvAuthReadiness(accountId, env = process.env) {
 	};
 }
 //#endregion
-export { resolveScopedMatrixEnvConfig as i, resolveGlobalMatrixEnvConfig as n, resolveMatrixEnvAuthReadiness as r, hasReadyMatrixEnvAuth as t };
+export { resolveMatrixEnvAuthReadiness as n, resolveScopedMatrixEnvConfig as r, resolveGlobalMatrixEnvConfig as t };

package/dist/{env-vars-B0NxQnPk.js → env-vars-dGqak9dN.js}

@@ -31,7 +31,7 @@ function decodeMatrixEnvAccountToken(token) {
 		if (hexEscape) {
 			const hex = hexEscape[1];
 			const codePoint = hex ? Number.parseInt(hex, 16) : NaN;
-			if (!Number.isFinite(codePoint)) return;
+			if (!Number.isInteger(codePoint) || codePoint > 1114111) return;
 			decoded += String.fromCodePoint(codePoint);
 			index += hexEscape[0].length;
 			continue;

package/dist/{errors-C47hvAF8.js → errors-DKVS3_DO.js}

@@ -1,11 +1,8 @@
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 //#region extensions/matrix/src/matrix/errors.ts
-function formatMatrixErrorMessage(err) {
-	return formatErrorMessage(err);
-}
 function formatMatrixErrorReason(err) {
-	return normalizeLowercaseStringOrEmpty(formatMatrixErrorMessage(err));
+	return normalizeLowercaseStringOrEmpty(formatErrorMessage(err));
 }
 function isMatrixNotFoundError(err) {
 	const errObj = err;
@@ -14,4 +11,4 @@ function isMatrixNotFoundError(err) {
 	return message.includes("m_not_found") || message.includes("[404]") || message.includes("not found");
 }
 //#endregion
-export { formatMatrixErrorReason as n, isMatrixNotFoundError as r, formatMatrixErrorMessage as t };
+export { isMatrixNotFoundError as n, formatMatrixErrorReason as t };

package/dist/{file-sync-store-DiiFsayX.js → file-sync-store-DjskBX2o.js}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
-import { t as isRecord } from "./record-shared-CWWx6fvI.js";
 import { t as getMatrixRuntime } from "./runtime-6S3DNFNv.js";
-import { M as resolveMatrixSqliteStateEnv, t as claimCurrentTokenStorageState } from "./storage-BvAkgzvT.js";
-import { n as LogService } from "./logger-D0GCSDQq.js";
+import { M as resolveMatrixSqliteStateEnv, t as claimCurrentTokenStorageState } from "./storage-BsGuHngK.js";
+import { n as LogService } from "./logger-B_71hN6W.js";
+import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -108,6 +108,7 @@ var SqliteBackedMatrixSyncStore = class extends MemoryStore {
 		this.savedSync = null;
 		this.cleanShutdown = false;
 		this.dirty = false;
+		this.frozen = false;
 		this.persistTimer = null;
 		this.persistPromise = null;
 		this.stateKey = SYNC_CACHE_STATE_KEY;
@@ -154,6 +155,7 @@ var SqliteBackedMatrixSyncStore = class extends MemoryStore {
 		return Promise.resolve(this.savedSync?.nextBatch ?? null);
 	}
 	setSyncData(syncData) {
+		if (this.frozen) return Promise.resolve();
 		this.accumulator.accumulate(syncData);
 		this.savedSync = this.accumulator.getJSON();
 		this.markDirtyAndSchedulePersist();
@@ -163,6 +165,7 @@ var SqliteBackedMatrixSyncStore = class extends MemoryStore {
 		return Promise.resolve(this.savedClientOptions ? cloneJson(this.savedClientOptions) : void 0);
 	}
 	storeClientOptions(options) {
+		if (this.frozen) return Promise.resolve();
 		this.savedClientOptions = cloneJson(options);
 		super.storeClientOptions(options);
 		this.markDirtyAndSchedulePersist();
@@ -195,6 +198,23 @@ var SqliteBackedMatrixSyncStore = class extends MemoryStore {
 		this.cleanShutdown = true;
 		this.dirty = true;
 	}
+	async freezeSyncCursorPersistence() {
+		this.frozen = true;
+		if (this.persistTimer) {
+			clearTimeout(this.persistTimer);
+			this.persistTimer = null;
+		}
+		await this.persistPromise;
+	}
+	discardPendingSyncCursorPersistence() {
+		this.frozen = true;
+		if (this.persistTimer) {
+			clearTimeout(this.persistTimer);
+			this.persistTimer = null;
+		}
+		this.cleanShutdown = false;
+		this.dirty = false;
+	}
 	async flush() {
 		if (this.persistTimer) {
 			clearTimeout(this.persistTimer);
@@ -208,6 +228,7 @@ var SqliteBackedMatrixSyncStore = class extends MemoryStore {
 		}
 	}
 	markDirtyAndSchedulePersist() {
+		if (this.frozen) return;
 		this.cleanShutdown = false;
 		this.dirty = true;
 		if (this.persistTimer) return;