@openclaw/matrix 2026.7.2-beta.7 → 2026.7.34

package/dist/{shared-CUMWxcMz.js → .setup/client-DFBQtzCe.mjs}

@@ -1,23 +1,26 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
-import { a as resolveMatrixDefaultOrOnlyAccountId, n as requiresExplicitMatrixDefaultAccount, o as resolveMatrixAccountStringValues } from "./account-selection-kqquRzCf.js";
-import { t as getMatrixScopedEnvVarNames } from "./env-vars-B0NxQnPk.js";
-import { o as resolveMatrixBaseConfig, r as listNormalizedMatrixAccountIds, t as findMatrixAccountConfig } from "./account-config-BZWN9tGS.js";
-import { i as resolveScopedMatrixEnvConfig, n as resolveGlobalMatrixEnvConfig } from "./env-auth-CQsYbz-p.js";
-import { t as resolveMatrixConfigFieldPath } from "./config-paths-CnREYb1Y.js";
-import { t as resolveValidatedMatrixHomeserverUrl } from "./url-validation-GRHde6lq.js";
-import { s as repairCurrentTokenStorageMetaDeviceId } from "./storage-BvAkgzvT.js";
-import { n as LogService } from "./logger-D0GCSDQq.js";
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+import { a as resolveMatrixDefaultOrOnlyAccountId, n as requiresExplicitMatrixDefaultAccount, s as resolveMatrixAccountStringValues } from "./account-selection-BOQeTqax.mjs";
+import { t as getMatrixScopedEnvVarNames } from "./env-vars-KzaYveuy.mjs";
+import { o as resolveMatrixBaseConfig, r as listNormalizedMatrixAccountIds, t as findMatrixAccountConfig } from "./account-config-BZWN9tGS.mjs";
+import { r as resolveScopedMatrixEnvConfig, t as resolveGlobalMatrixEnvConfig } from "./env-auth-CYJL1jNl.mjs";
+import { t as resolveMatrixConfigFieldPath } from "./config-paths-CnREYb1Y.mjs";
+import { t as resolveValidatedMatrixHomeserverUrl } from "./url-validation-GRHde6lq.mjs";
+import { d as writeStorageMeta, l as resolveMatrixStoragePaths, r as maybeMigrateLegacyStorage, s as repairCurrentTokenStorageMetaDeviceId } from "./storage-NGZq5zet.mjs";
+import { n as LogService } from "./logger-DpoogOgz.mjs";
 import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { DEFAULT_ACCOUNT_ID as DEFAULT_ACCOUNT_ID$1, normalizeAccountId as normalizeAccountId$1, normalizeOptionalAccountId, normalizeOptionalAccountId as normalizeOptionalAccountId$1 } from "openclaw/plugin-sdk/account-id";
 import { coerceSecretRef, normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input-runtime";
-import { formatErrorMessage, toErrorObject } from "openclaw/plugin-sdk/error-runtime";
-import { isPrivateNetworkOptInEnabled, ssrfPolicyFromDangerouslyAllowPrivateNetwork as ssrfPolicyFromDangerouslyAllowPrivateNetwork$1 } from "openclaw/plugin-sdk/ssrf-runtime";
+import fs from "node:fs";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { isPrivateNetworkOptInEnabled, ssrfPolicyFromDangerouslyAllowPrivateNetwork, ssrfPolicyFromDangerouslyAllowPrivateNetwork as ssrfPolicyFromDangerouslyAllowPrivateNetwork$1 } from "openclaw/plugin-sdk/ssrf-runtime";
 import { resolveOptionalIntegerOption } from "openclaw/plugin-sdk/number-runtime";
 import { requireRuntimeConfig } from "openclaw/plugin-sdk/plugin-config-runtime";
 import { retryAsync } from "openclaw/plugin-sdk/retry-runtime";
-import { sleepWithAbort } from "openclaw/plugin-sdk/runtime-env";
+import { createDeferred } from "openclaw/plugin-sdk/extension-shared";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region extensions/matrix/src/matrix/client/config.ts
-const loadDefaultMatrixAuthClientDeps = createLazyRuntimeModule(() => Promise.all([import("./sdk-bUytQHx7.js"), import("./logging-DV-p52N0.js").then((n) => n.n)]).then(([sdkModule, loggingModule]) => ({
+const loadDefaultMatrixAuthClientDeps = createLazyRuntimeModule(() => Promise.all([import("./sdk-He1quVAq.mjs").then((n) => n.t), import("./logging-CgxQOJJP.mjs")]).then(([sdkModule, loggingModule]) => ({
 	MatrixClient: sdkModule.MatrixClient,
 	ensureMatrixSdkLoggingConfigured: loggingModule.ensureMatrixSdkLoggingConfigured
 })));
@@ -25,12 +28,12 @@ const MATRIX_AUTH_REQUEST_RETRY_RE = /\b(fetch failed|econnreset|econnrefused|en
 async function loadMatrixAuthClientDeps() {
 	return await loadDefaultMatrixAuthClientDeps();
 }
-const loadMatrixCredentialsReadDeps = createLazyRuntimeModule(() => import("./credentials-read-DVmFCm7X.js").then((n) => n.i).then((credentialsReadModule) => ({
+const loadMatrixCredentialsReadDeps = createLazyRuntimeModule(() => import("./credentials-read-CRHg6XPm.mjs").then((n) => n.r).then((credentialsReadModule) => ({
 	loadMatrixCredentials: credentialsReadModule.loadMatrixCredentials,
 	credentialsMatchConfig: credentialsReadModule.credentialsMatchConfig
 })));
-const loadMatrixCredentialsWriteRuntime = createLazyRuntimeModule(() => import("./credentials-write.runtime-Be9zNSUw.js"));
-const loadMatrixSecretInputDeps = createLazyRuntimeModule(() => import("./config-secret-input.runtime-CwsP3--c.js").then((runtime) => ({ resolveConfiguredSecretInputString: runtime.resolveConfiguredSecretInputString })));
+const loadMatrixCredentialsWriteRuntime = createLazyRuntimeModule(() => import("./credentials-write.runtime-dWuLafsk.mjs"));
+const loadMatrixSecretInputDeps = createLazyRuntimeModule(() => import("./config-secret-input.runtime-CwsP3--c.mjs").then((runtime) => ({ resolveConfiguredSecretInputString: runtime.resolveConfiguredSecretInputString })));
 function shouldRetryMatrixAuthRequest(err) {
 	return MATRIX_AUTH_REQUEST_RETRY_RE.test(formatErrorMessage(err));
 }
@@ -41,15 +44,14 @@ function credentialsMatchBackfillAuthLineage(params) {
 	if (!params.stored) return true;
 	return params.stored.homeserver === params.auth.homeserver && params.stored.userId === params.auth.userId && params.stored.accessToken === params.auth.accessToken;
 }
-async function retryMatrixAuthRequest(label, run, signal) {
+async function retryMatrixAuthRequest(label, run) {
 	return await retryAsync(run, {
 		attempts: 3,
 		minDelayMs: 250,
 		maxDelayMs: 1500,
 		jitter: .1,
 		label,
-		shouldRetry: (err) => shouldRetryMatrixAuthRequest(err),
-		sleep: (ms) => sleepWithAbort(ms, signal)
+		shouldRetry: (err) => shouldRetryMatrixAuthRequest(err)
 	});
 }
 async function fetchMatrixWhoamiIdentity(params) {
@@ -62,7 +64,7 @@ async function fetchMatrixWhoamiIdentity(params) {
 	});
 	return await retryMatrixAuthRequest("matrix auth whoami", async () => {
 		return await tempClient.doRequest("GET", "/_matrix/client/v3/account/whoami");
-	}, params.signal);
+	});
 }
 function readEnvSecretRefFallback(params) {
 	const ref = coerceSecretRef(params.value, params.config?.secrets?.defaults);
@@ -80,12 +82,13 @@ function readEnvSecretRefFallback(params) {
 function clean(value, path, opts) {
 	const ref = coerceSecretRef(value, opts?.config?.secrets?.defaults);
 	if (opts?.suppressSecretRef && ref) return "";
+	const normalizedValue = opts?.allowEnvSecretRefFallback ? ref?.source === "env" ? readEnvSecretRefFallback({
+		value,
+		env: opts.env,
+		config: opts.config
+	}) ?? value : ref ? "" : value : value;
 	return normalizeResolvedSecretInputString({
-		value: opts?.allowEnvSecretRefFallback ? ref?.source === "env" ? readEnvSecretRefFallback({
-			value,
-			env: opts.env,
-			config: opts.config
-		}) ?? value : ref ? "" : value : value,
+		value: normalizedValue,
 		path,
 		defaults: opts?.config?.secrets?.defaults
 	}) ?? "";
@@ -256,15 +259,10 @@ function resolveImplicitMatrixAccountId(cfg, env = process.env) {
 function resolveMatrixAuthContext(params) {
 	const cfg = requireRuntimeConfig(params.cfg, "Matrix auth context");
 	const env = params?.env ?? process.env;
-	const requestedAccountId = params?.accountId?.trim();
 	const explicitAccountId = normalizeOptionalAccountId$1(params?.accountId);
-	if (requestedAccountId && !explicitAccountId) throw new Error(`Matrix account id "${requestedAccountId}" is invalid.`);
 	const effectiveAccountId = explicitAccountId ?? resolveImplicitMatrixAccountId(cfg, env);
 	if (!effectiveAccountId) throw new Error("Multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set. Set \"channels.matrix.defaultAccount\" to the intended account or pass --account <id>.");
 	if (explicitAccountId && explicitAccountId !== DEFAULT_ACCOUNT_ID$1 && !listNormalizedMatrixAccountIds(cfg).includes(explicitAccountId) && !hasScopedMatrixEnvConfig(explicitAccountId, env)) throw new Error(`Matrix account "${explicitAccountId}" is not configured. Add channels.matrix.accounts.${explicitAccountId} or define scoped ${getMatrixScopedEnvVarNames(explicitAccountId).accessToken.replace(/_ACCESS_TOKEN$/, "")}_* variables.`);
-	const matrix = resolveMatrixBaseConfig(cfg);
-	const account = findMatrixAccountConfig(cfg, effectiveAccountId);
-	if (matrix.enabled === false || account?.enabled === false) throw new Error(`Matrix account "${effectiveAccountId}" is disabled.`);
 	return {
 		cfg,
 		env,
@@ -414,21 +412,13 @@ async function backfillMatrixAuthDeviceIdAfterStartup(params) {
 	const knownDeviceId = params.auth.deviceId?.trim();
 	if (knownDeviceId) return knownDeviceId;
 	if (isAbortSignalTriggered(params.abortSignal)) return;
-	let whoami;
-	try {
-		whoami = await fetchMatrixWhoamiIdentity({
-			homeserver: params.auth.homeserver,
-			accessToken: params.auth.accessToken,
-			userId: params.auth.userId,
-			ssrfPolicy: params.auth.ssrfPolicy,
-			dispatcherPolicy: params.auth.dispatcherPolicy,
-			signal: params.abortSignal
-		});
-	} catch (err) {
-		if (isAbortSignalTriggered(params.abortSignal)) return;
-		throw err;
-	}
-	const deviceId = whoami.device_id?.trim();
+	const deviceId = (await fetchMatrixWhoamiIdentity({
+		homeserver: params.auth.homeserver,
+		accessToken: params.auth.accessToken,
+		userId: params.auth.userId,
+		ssrfPolicy: params.auth.ssrfPolicy,
+		dispatcherPolicy: params.auth.dispatcherPolicy
+	})).device_id?.trim();
 	if (!deviceId) return;
 	if (isAbortSignalTriggered(params.abortSignal)) return;
 	const env = params.env ?? process.env;
@@ -454,6 +444,96 @@ async function backfillMatrixAuthDeviceIdAfterStartup(params) {
 	}, env, params.auth.accountId) === "saved" ? deviceId : void 0;
 }
 //#endregion
+//#region extensions/matrix/src/matrix/client/create-client.ts
+var create_client_exports = /* @__PURE__ */ __exportAll({ createMatrixClient: () => createMatrixClient });
+const loadMatrixCreateClientRuntimeDeps = createLazyRuntimeModule(() => Promise.all([import("./sdk-He1quVAq.mjs").then((n) => n.t), import("./logging-CgxQOJJP.mjs")]).then(([sdkModule, loggingModule]) => ({
+	MatrixClient: sdkModule.MatrixClient,
+	ensureMatrixSdkLoggingConfigured: loggingModule.ensureMatrixSdkLoggingConfigured
+})));
+async function createMatrixClient(params) {
+	const { MatrixClient, ensureMatrixSdkLoggingConfigured } = await loadMatrixCreateClientRuntimeDeps();
+	ensureMatrixSdkLoggingConfigured();
+	const homeserver = await resolveValidatedMatrixHomeserverUrl(params.homeserver, { dangerouslyAllowPrivateNetwork: params.allowPrivateNetwork });
+	const matrixClientUserId = normalizeOptionalString(params.userId);
+	const userId = matrixClientUserId ?? "unknown";
+	const storagePaths = params.persistStorage !== false ? resolveMatrixStoragePaths({
+		homeserver,
+		userId,
+		accessToken: params.accessToken,
+		accountId: params.accountId,
+		deviceId: params.deviceId,
+		env: process.env
+	}) : null;
+	if (storagePaths) {
+		await maybeMigrateLegacyStorage({
+			storagePaths,
+			env: process.env
+		});
+		fs.mkdirSync(storagePaths.rootDir, { recursive: true });
+		writeStorageMeta({
+			storagePaths,
+			homeserver,
+			userId,
+			accountId: params.accountId,
+			deviceId: params.deviceId
+		});
+	}
+	const cryptoDatabasePrefix = storagePaths ? `openclaw-matrix-${storagePaths.accountKey}-${storagePaths.tokenHash}` : void 0;
+	return new MatrixClient(homeserver, params.accessToken, {
+		userId: matrixClientUserId,
+		password: params.password,
+		deviceId: params.deviceId,
+		encryption: params.encryption,
+		localTimeoutMs: params.localTimeoutMs,
+		initialSyncLimit: params.initialSyncLimit,
+		storageRootDir: storagePaths?.rootDir,
+		recoveryKeyPath: storagePaths?.recoveryKeyPath,
+		idbSnapshotPath: storagePaths?.idbSnapshotPath,
+		cryptoDatabasePrefix,
+		autoBootstrapCrypto: params.autoBootstrapCrypto,
+		ssrfPolicy: params.ssrfPolicy ?? ssrfPolicyFromDangerouslyAllowPrivateNetwork(params.allowPrivateNetwork),
+		dispatcherPolicy: params.dispatcherPolicy
+	});
+}
+//#endregion
+//#region extensions/matrix/src/matrix/monitor/task-runner.ts
+const monitorTaskSignal = new AsyncLocalStorage();
+function getMatrixMonitorTaskSignal() {
+	return monitorTaskSignal.getStore();
+}
+function createMatrixMonitorTaskRunner(params) {
+	const inFlight = /* @__PURE__ */ new Map();
+	let closed = false;
+	const runDetachedTask = (label, task) => {
+		if (closed) return Promise.resolve();
+		const controller = new AbortController();
+		const trackedTask = monitorTaskSignal.run(controller.signal, () => Promise.resolve().then(task)).catch((error) => {
+			const message = String(error);
+			params.logVerboseMessage(`matrix: ${label} failed (${message})`);
+			params.logger.warn("matrix background task failed", {
+				task: label,
+				error: message
+			});
+		}).finally(() => {
+			controller.abort();
+			inFlight.delete(trackedTask);
+		});
+		inFlight.set(trackedTask, controller);
+		return trackedTask;
+	};
+	const waitForIdle = async () => {
+		while (inFlight.size > 0) await Promise.allSettled(Array.from(inFlight.keys()));
+	};
+	return {
+		close: () => {
+			closed = true;
+			for (const controller of inFlight.values()) controller.abort();
+		},
+		runDetachedTask,
+		waitForIdle
+	};
+}
+//#endregion
 //#region extensions/matrix/src/matrix/startup-abort.ts
 function createMatrixStartupAbortError() {
 	const error = /* @__PURE__ */ new Error("Matrix startup aborted");
@@ -480,22 +560,21 @@ async function awaitMatrixStartupWithAbort(promise, abortSignal) {
 			resolve(value);
 		}, (error) => {
 			abortSignal.removeEventListener("abort", onAbort);
-			reject(toErrorObject(error, "Non-Error rejection"));
+			reject(toLintErrorObject(error, "Non-Error rejection"));
 		});
 	});
 }
+function toLintErrorObject(value, fallbackMessage) {
+	if (value instanceof Error) return value;
+	if (typeof value === "string") return new Error(value);
+	const error = new Error(fallbackMessage, { cause: value });
+	if (typeof value === "object" && value !== null || typeof value === "function") Object.assign(error, value);
+	return error;
+}
 //#endregion
 //#region extensions/matrix/src/matrix/client/shared.ts
-var shared_exports = /* @__PURE__ */ __exportAll({
-	acquireSharedMatrixClient: () => acquireSharedMatrixClient,
-	releaseSharedClientInstance: () => releaseSharedClientInstance,
-	removeSharedClientInstance: () => removeSharedClientInstance,
-	resolveSharedMatrixClient: () => resolveSharedMatrixClient,
-	stopSharedClient: () => stopSharedClient,
-	stopSharedClientForAccount: () => stopSharedClientForAccount,
-	stopSharedClientInstance: () => stopSharedClientInstance
-});
-const loadMatrixCreateClientDeps = createLazyRuntimeModule(() => import("./create-client-BmSU-q-D.js").then((n) => n.n).then((runtime) => ({ createMatrixClient: runtime.createMatrixClient })));
+const loadMatrixCreateClientDeps = createLazyRuntimeModule(() => Promise.resolve().then(() => create_client_exports).then((runtime) => ({ createMatrixClient: runtime.createMatrixClient })));
+const MATRIX_RETIREMENT_DRAIN_TIMEOUT_MS = 5e3;
 const sharedClientStates = /* @__PURE__ */ new Map();
 const sharedClientPromises = /* @__PURE__ */ new Map();
 function serializeDispatcherPolicyKey(auth) {
@@ -514,160 +593,324 @@ function buildSharedClientKey(auth) {
 }
 async function createSharedMatrixClient(params) {
 	const { createMatrixClient } = await loadMatrixCreateClientDeps();
+	const client = await createMatrixClient({
+		homeserver: params.auth.homeserver,
+		userId: params.auth.userId,
+		accessToken: params.auth.accessToken,
+		password: params.auth.password,
+		deviceId: params.auth.deviceId,
+		encryption: params.auth.encryption,
+		localTimeoutMs: params.timeoutMs,
+		initialSyncLimit: params.auth.initialSyncLimit,
+		accountId: params.auth.accountId,
+		allowPrivateNetwork: params.auth.allowPrivateNetwork,
+		ssrfPolicy: params.auth.ssrfPolicy,
+		dispatcherPolicy: params.auth.dispatcherPolicy
+	});
 	return {
-		client: await createMatrixClient({
-			homeserver: params.auth.homeserver,
-			userId: params.auth.userId,
-			accessToken: params.auth.accessToken,
-			password: params.auth.password,
-			deviceId: params.auth.deviceId,
-			encryption: params.auth.encryption,
-			localTimeoutMs: params.timeoutMs,
-			initialSyncLimit: params.auth.initialSyncLimit,
-			accountId: params.auth.accountId,
-			allowPrivateNetwork: params.auth.allowPrivateNetwork,
-			ssrfPolicy: params.auth.ssrfPolicy,
-			dispatcherPolicy: params.auth.dispatcherPolicy
-		}),
+		auth: params.auth,
+		client,
 		key: buildSharedClientKey(params.auth),
 		started: false,
 		cryptoReady: false,
+		startAbortController: null,
 		startPromise: null,
-		leases: 0
+		phase: "open",
+		leases: /* @__PURE__ */ new Set(),
+		monitorRetirementPromises: /* @__PURE__ */ new Set(),
+		noLeases: createDeferred(),
+		retirementPromise: null,
+		poisonError: null,
+		releaseMode: "discard"
 	};
 }
-function findSharedClientStateByInstance(client) {
-	for (const state of sharedClientStates.values()) if (state.client === client) return state;
-	return null;
-}
 function deleteSharedClientState(state) {
-	sharedClientStates.delete(state.key);
+	if (sharedClientStates.get(state.key) === state) sharedClientStates.delete(state.key);
 	sharedClientPromises.delete(state.key);
 }
-async function ensureSharedClientStarted(params) {
-	const waitForStart = async (startPromise) => {
-		await awaitMatrixStartupWithAbort(startPromise, params.abortSignal);
-	};
-	if (params.state.started) return;
-	if (params.state.startPromise) {
-		await waitForStart(params.state.startPromise);
+async function ensureSharedClientStarted(state, abortSignal) {
+	if (state.started) return;
+	if (state.startPromise) {
+		await awaitMatrixStartupWithAbort(state.startPromise, abortSignal);
 		return;
 	}
+	const startAbortController = new AbortController();
+	state.startAbortController = startAbortController;
 	const guardedStart = (async () => {
-		const client = params.state.client;
-		if (params.encryption && !params.state.cryptoReady) try {
-			const joinedRooms = await client.getJoinedRooms();
-			if (client.crypto) {
-				await client.crypto.prepare(joinedRooms);
-				params.state.cryptoReady = true;
+		if (state.auth.encryption && !state.cryptoReady) try {
+			const joinedRooms = await state.client.getJoinedRooms();
+			if (state.client.crypto) {
+				await state.client.crypto.prepare(joinedRooms);
+				state.cryptoReady = true;
 			}
 		} catch (err) {
 			LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
 		}
-		await client.start({ abortSignal: params.abortSignal });
-		params.state.started = true;
+		await state.client.start({ abortSignal: startAbortController.signal });
+		throwIfMatrixStartupAborted(startAbortController.signal);
+		if (state.phase !== "open") throwIfMatrixStartupAborted(AbortSignal.abort());
+		state.started = true;
 	})().finally(() => {
-		if (params.state.startPromise === guardedStart) params.state.startPromise = null;
+		if (state.startPromise === guardedStart) {
+			state.startPromise = null;
+			state.startAbortController = null;
+		}
 	});
-	params.state.startPromise = guardedStart;
-	await waitForStart(guardedStart);
+	state.startPromise = guardedStart;
+	await awaitMatrixStartupWithAbort(guardedStart, abortSignal);
 }
-async function resolveSharedMatrixClientState(params = {}) {
+async function resolveSharedMatrixAuth(params) {
 	const requestedAccountId = normalizeOptionalAccountId(params.accountId);
 	if (params.auth && requestedAccountId && requestedAccountId !== params.auth.accountId) throw new Error(`Matrix shared client account mismatch: requested ${requestedAccountId}, auth resolved ${params.auth.accountId}`);
-	const authContext = (() => {
-		if (params.auth) return null;
-		if (!params.cfg) throw new Error("Matrix shared client requires a resolved runtime config. Load and resolve config at the command or gateway boundary, then pass cfg through the runtime path.");
-		return resolveMatrixAuthContext({
-			cfg: params.cfg,
-			env: params.env,
-			accountId: params.accountId
-		});
-	})();
-	const auth = params.auth ?? await resolveMatrixAuth({
-		cfg: authContext?.cfg ?? params.cfg,
-		env: authContext?.env ?? params.env,
-		accountId: authContext?.accountId
+	if (params.auth) return params.auth;
+	if (!params.cfg) throw new Error("Matrix shared client requires a resolved runtime config. Load and resolve config at the command or gateway boundary, then pass cfg through the runtime path.");
+	const authContext = resolveMatrixAuthContext({
+		cfg: params.cfg,
+		env: params.env,
+		accountId: params.accountId
+	});
+	return await resolveMatrixAuth({
+		cfg: authContext.cfg,
+		env: authContext.env,
+		accountId: authContext.accountId
 	});
+}
+async function resolveOpenSharedMatrixClientState(params) {
+	const auth = await resolveSharedMatrixAuth(params);
 	const key = buildSharedClientKey(auth);
-	const shouldStart = params.startClient !== false;
-	const existingState = sharedClientStates.get(key);
-	if (existingState) {
-		if (shouldStart) await ensureSharedClientStarted({
-			state: existingState,
-			encryption: auth.encryption,
-			abortSignal: params.abortSignal
-		});
-		return existingState;
-	}
-	const existingPromise = sharedClientPromises.get(key);
-	if (existingPromise) {
-		const pending = await existingPromise;
-		if (shouldStart) await ensureSharedClientStarted({
-			state: pending,
-			encryption: auth.encryption,
-			abortSignal: params.abortSignal
+	while (true) {
+		const existing = sharedClientStates.get(key);
+		if (existing?.poisonError) throw existing.poisonError;
+		if (existing?.phase === "open") return existing;
+		if (existing?.retirementPromise) {
+			await awaitMatrixStartupWithAbort(existing.retirementPromise, params.abortSignal);
+			continue;
+		}
+		const pending = sharedClientPromises.get(key);
+		if (pending) {
+			await awaitMatrixStartupWithAbort(pending, params.abortSignal);
+			continue;
+		}
+		const creationPromise = createSharedMatrixClient({
+			auth,
+			timeoutMs: params.timeoutMs
 		});
-		return pending;
+		sharedClientPromises.set(key, creationPromise);
+		try {
+			const created = await creationPromise;
+			sharedClientStates.set(key, created);
+			return created;
+		} finally {
+			sharedClientPromises.delete(key);
+		}
 	}
-	const creationPromise = createSharedMatrixClient({
-		auth,
-		timeoutMs: params.timeoutMs
-	});
-	sharedClientPromises.set(key, creationPromise);
+}
+async function runMonitorRetirement(retirement) {
+	if (!retirement) return;
+	retirement.closeTaskAdmission();
+	retirement.detachListeners();
+	await retirement.waitForTasks();
+	await retirement.cleanup();
+}
+function retireMonitorLease(state, lease) {
+	if (lease.monitorRetirementPromise) return lease.monitorRetirementPromise;
+	lease.monitorRetirementPromise = runMonitorRetirement(lease.monitorRetirement ?? void 0);
+	state.monitorRetirementPromises.add(lease.monitorRetirementPromise);
+	return lease.monitorRetirementPromise;
+}
+async function retireMonitorLeases(state, leases) {
+	for (const lease of leases) retireMonitorLease(state, lease);
+	const failure = (await Promise.allSettled(state.monitorRetirementPromises)).find((result) => result.status === "rejected");
+	if (failure?.status === "rejected") throw failure.reason;
+}
+function toRetirementError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+function mergeReleaseMode(current, requested) {
+	if (current === "persist" || requested === "persist") return "persist";
+	if (current === "stop" || requested === "stop") return "stop";
+	return "discard";
+}
+function abortTransientLeases(state) {
+	for (const lease of state.leases) if (lease.role === "transient") lease.abortController.abort();
+}
+async function waitForRetirementDrain(state, task, isPending, timeoutMessage) {
+	if (!isPending()) return;
+	let deadline;
 	try {
-		const created = await creationPromise;
-		sharedClientStates.set(key, created);
-		if (shouldStart) await ensureSharedClientStarted({
-			state: created,
-			encryption: auth.encryption,
-			abortSignal: params.abortSignal
-		});
-		return created;
+		await Promise.race([task, new Promise((_, reject) => {
+			deadline = setTimeout(() => {
+				if (!isPending()) return;
+				state.phase = "late-drain";
+				reject(new Error(timeoutMessage));
+			}, MATRIX_RETIREMENT_DRAIN_TIMEOUT_MS);
+			deadline.unref?.();
+		})]);
 	} finally {
-		sharedClientPromises.delete(key);
+		if (deadline) clearTimeout(deadline);
 	}
 }
-async function resolveSharedMatrixClient(params = {}) {
-	return (await resolveSharedMatrixClientState(params)).client;
+function beginGenerationRetirement(params) {
+	const { state } = params;
+	if (state.retirementPromise) return state.retirementPromise;
+	state.phase = "quiescing";
+	state.startAbortController?.abort();
+	const result = createDeferred();
+	state.retirementPromise = result.promise;
+	Promise.resolve().then(async () => {
+		let canReplacePoisonedGeneration = false;
+		const startup = state.startPromise;
+		if (startup) try {
+			await waitForRetirementDrain(state, startup.catch(() => void 0), () => state.startPromise === startup, `Matrix client startup did not settle within ${MATRIX_RETIREMENT_DRAIN_TIMEOUT_MS}ms during retirement`);
+		} catch (error) {
+			state.poisonError = toRetirementError(error);
+			result.reject(state.poisonError);
+			await Promise.allSettled([
+				startup.catch(() => void 0).then(() => {
+					state.started = false;
+					state.client.stopWithoutPersist();
+				}),
+				retireMonitorLeases(state, params.monitorLeases ?? []),
+				state.noLeases.promise
+			]);
+			deleteSharedClientState(state);
+			throw state.poisonError;
+		}
+		try {
+			await state.client.quiesceSync();
+			state.started = false;
+			await state.client.drainPendingDecryptions("matrix monitor sync quiesce");
+		} catch (error) {
+			state.poisonError = toRetirementError(error);
+			canReplacePoisonedGeneration = true;
+		}
+		try {
+			await retireMonitorLeases(state, params.monitorLeases ?? []);
+		} catch (error) {
+			state.poisonError ??= toRetirementError(error);
+			canReplacePoisonedGeneration = false;
+		}
+		state.phase = "closing";
+		let lateLeaseDrain = null;
+		try {
+			await waitForRetirementDrain(state, state.noLeases.promise, () => state.leases.size > 0, `Matrix transient leases did not drain within ${MATRIX_RETIREMENT_DRAIN_TIMEOUT_MS}ms`);
+		} catch (error) {
+			state.poisonError ??= toRetirementError(error);
+			canReplacePoisonedGeneration = false;
+			result.reject(state.poisonError);
+			lateLeaseDrain = state.noLeases.promise;
+		}
+		if (state.poisonError) {
+			const decryptionsDrained = await state.client.drainPendingDecryptions("matrix poisoned client shutdown").then(() => true, () => false);
+			state.client.stopWithoutPersist();
+			await lateLeaseDrain;
+			if (lateLeaseDrain || canReplacePoisonedGeneration && decryptionsDrained) deleteSharedClientState(state);
+			throw state.poisonError;
+		}
+		try {
+			await state.client.drainPendingDecryptions("matrix shared client final shutdown");
+		} catch (error) {
+			state.poisonError = toRetirementError(error);
+			try {
+				state.client.stopWithoutPersist();
+			} finally {
+				deleteSharedClientState(state);
+			}
+			throw state.poisonError;
+		}
+		try {
+			if (state.releaseMode === "persist") await state.client.stopAndPersist();
+			else if (state.releaseMode === "discard") state.client.stopWithoutPersist();
+			else await state.client.stopAndPersist().catch(() => state.client.stopWithoutPersist());
+		} finally {
+			await lateLeaseDrain;
+			deleteSharedClientState(state);
+		}
+	}).then(result.resolve, result.reject);
+	abortTransientLeases(state);
+	return state.retirementPromise;
+}
+function createSharedMatrixClientLease(state, role) {
+	if (state.phase !== "open" || state.poisonError) return null;
+	const leaseState = {
+		abortController: new AbortController(),
+		monitorRetirement: null,
+		monitorRetirementPromise: null,
+		role,
+		releasePromise: null
+	};
+	state.leases.add(leaseState);
+	return {
+		abortSignal: leaseState.abortController.signal,
+		client: state.client,
+		role,
+		registerMonitorRetirement: (retirement) => {
+			if (role !== "monitor") throw new Error("Matrix transient leases cannot register monitor retirement");
+			if (leaseState.releasePromise || state.phase !== "open") throw new Error("Matrix monitor lease is already retiring");
+			if (leaseState.monitorRetirement && leaseState.monitorRetirement !== retirement) throw new Error("Matrix monitor retirement is already registered");
+			leaseState.monitorRetirement = retirement;
+		},
+		start: async (abortSignal) => {
+			if (leaseState.releasePromise) throw new Error("Matrix client lease has already been released");
+			if (state.phase !== "open") throw new Error("Matrix client generation is retiring");
+			await ensureSharedClientStarted(state, abortSignal ? AbortSignal.any([abortSignal, leaseState.abortController.signal]) : leaseState.abortController.signal);
+		},
+		release: (releaseParams = {}) => {
+			if (leaseState.releasePromise) return leaseState.releasePromise;
+			state.releaseMode = mergeReleaseMode(state.releaseMode, releaseParams.mode ?? "stop");
+			state.leases.delete(leaseState);
+			if (state.leases.size === 0) state.noLeases.resolve();
+			if (state.phase === "late-drain") {
+				leaseState.releasePromise = Promise.resolve();
+				return leaseState.releasePromise;
+			}
+			const finalMonitor = role === "monitor" && !Array.from(state.leases).some((lease) => lease.role === "monitor");
+			if (role === "monitor" && !finalMonitor) {
+				leaseState.releasePromise = retireMonitorLease(state, leaseState);
+				return leaseState.releasePromise;
+			}
+			if (!(state.phase === "open" && (finalMonitor || state.leases.size === 0))) {
+				leaseState.releasePromise = state.poisonError ? Promise.reject(state.poisonError) : Promise.resolve();
+				return leaseState.releasePromise;
+			}
+			leaseState.releasePromise = beginGenerationRetirement({
+				state,
+				monitorLeases: role === "monitor" ? [leaseState] : void 0
+			});
+			return leaseState.releasePromise;
+		}
+	};
 }
 async function acquireSharedMatrixClient(params = {}) {
-	const state = await resolveSharedMatrixClientState(params);
-	state.leases += 1;
-	return state.client;
-}
-function stopSharedClient() {
-	for (const state of sharedClientStates.values()) state.client.stop();
-	sharedClientStates.clear();
-	sharedClientPromises.clear();
-}
-function stopSharedClientForAccount(auth) {
-	const key = buildSharedClientKey(auth);
-	const state = sharedClientStates.get(key);
-	if (!state) return;
-	state.client.stop();
-	deleteSharedClientState(state);
-}
-function removeSharedClientInstance(client) {
-	const state = findSharedClientStateByInstance(client);
-	if (!state) return false;
-	deleteSharedClientState(state);
-	return true;
-}
-function stopSharedClientInstance(client) {
-	if (!removeSharedClientInstance(client)) return;
-	client.stop();
-}
-async function releaseSharedClientInstance(client, mode = "stop") {
-	const state = findSharedClientStateByInstance(client);
-	if (!state) return false;
-	state.leases = Math.max(0, state.leases - 1);
-	if (state.leases > 0) return false;
-	deleteSharedClientState(state);
-	if (mode === "persist") await client.stopAndPersist();
-	else if (mode === "discard") client.stopWithoutPersist();
-	else client.stop();
-	return true;
+	const taskSignal = getMatrixMonitorTaskSignal();
+	const abortSignal = taskSignal && params.abortSignal ? AbortSignal.any([taskSignal, params.abortSignal]) : taskSignal ?? params.abortSignal;
+	const acquisition = {
+		...params,
+		abortSignal
+	};
+	while (true) {
+		throwIfMatrixStartupAborted(abortSignal);
+		const state = await resolveOpenSharedMatrixClientState(acquisition);
+		if (abortSignal?.aborted) {
+			if (state.phase === "open" && state.leases.size === 0) await beginGenerationRetirement({ state });
+			throwIfMatrixStartupAborted(abortSignal);
+		}
+		const lease = createSharedMatrixClientLease(state, params.role ?? "transient");
+		if (!lease) continue;
+		if (params.startClient !== false) try {
+			await lease.start(abortSignal);
+		} catch (error) {
+			await lease.release({ mode: "stop" }).catch(() => void 0);
+			throw error;
+		}
+		return lease;
+	}
 }
 //#endregion
-export { shared_exports as a, createMatrixStartupAbortError as c, backfillMatrixAuthDeviceIdAfterStartup as d, resolveMatrixAuth as f, resolveSharedMatrixClient as i, isMatrixStartupAbortError as l, resolveMatrixConfigForAccount as m, releaseSharedClientInstance as n, stopSharedClientForAccount as o, resolveMatrixAuthContext as p, removeSharedClientInstance as r, stopSharedClientInstance as s, acquireSharedMatrixClient as t, throwIfMatrixStartupAborted as u };
+//#region extensions/matrix/src/matrix/client.ts
+var client_exports = /* @__PURE__ */ __exportAll({
+	acquireSharedMatrixClient: () => acquireSharedMatrixClient,
+	resolveMatrixAuthContext: () => resolveMatrixAuthContext
+});
+//#endregion
+export { throwIfMatrixStartupAborted as a, backfillMatrixAuthDeviceIdAfterStartup as c, isMatrixStartupAbortError as i, resolveMatrixAuth as l, acquireSharedMatrixClient as n, createMatrixMonitorTaskRunner as o, createMatrixStartupAbortError as r, createMatrixClient as s, client_exports as t, resolveMatrixAuthContext as u };