@alfe.ai/integrations 0.2.5 → 0.2.7

package/dist/index.d.ts

@@ -746,6 +746,79 @@ declare function runHook(integrationPath: string, hookScript: string, env?: Reco
  */
 declare function runHookWithContext(integrationPath: string, hookScript: string, options: HookEnvOptions): Promise<HookResult>;
 //#endregion
+//#region src/openclaw-cli-lock.d.ts
+/**
+ * OpenClawCliLock — one process-wide async mutex that every openclaw
+ * config/state-mutating CLI invocation acquires.
+ *
+ * ## Why this exists
+ *
+ * OpenClaw's config store uses OPTIMISTIC CONCURRENCY — a `config set` /
+ * `plugins install` reads the current config version, applies its change, and
+ * writes back only if the version is unchanged. Two openclaw CLI processes that
+ * mutate the store concurrently therefore lose the race: the second write fails
+ * with `ConfigMutationConflictError: config changed since last load` (exit 1).
+ * And when the long-running runtime (`openclaw gateway run`) is ALSO writing the
+ * same `~/.openclaw/state/openclaw.sqlite`, two independent SQLite writers with
+ * no shared locking corrupt the DB ("database disk image is malformed").
+ *
+ * During a DESIRED_STATE reconcile the daemon fires a SWARM of openclaw CLI
+ * processes — integration `config set` / `plugins install/uninstall`, the
+ * mcp-cleanup `config unset`, the `alfe.config_set` raw write — all mutating the
+ * one config store at the same time. This lock serializes ALL of them into a
+ * single strict queue so no two openclaw mutations ever overlap.
+ *
+ * This is the second of two layers. The first is the gateway's `RuntimeGate`,
+ * which suspends the runtime CHILD around mutating reconcile branches (so the
+ * runtime isn't writing while a CLI subprocess is). This lock covers the daemon's
+ * OWN subprocesses racing EACH OTHER — including cross-subsystem races the
+ * RuntimeGate doesn't see (mcp-cleanup vs a reconcile plugins-install, a raw
+ * `alfe.config_set` vs an in-flight integration apply). Both layers are needed.
+ *
+ * ## Read-modify-write atomicity
+ *
+ * A `config get` whose value is then written back (e.g. read `plugins.allow`,
+ * union in a plugin, write it back) MUST hold the lock across the WHOLE get→set,
+ * not lock the get and set independently — otherwise another openclaw process can
+ * mutate the same key between the read and the write and the write clobbers it.
+ * Callers pass the entire read-modify-write as one `lock.run(async () => { … })`.
+ *
+ * ## Re-entrancy
+ *
+ * This is a plain promise-chain mutex — it is NOT re-entrant. A `run()` callback
+ * MUST NOT call `run()` again (it would deadlock: the inner call chains behind
+ * the outer, which can't complete until the inner does). Consumers keep their
+ * locked-section internals as UNLOCKED helpers and acquire the lock exactly once
+ * at the public entry point.
+ */
+interface OpenClawCliLock {
+  /**
+   * Run `fn` with exclusive access to the openclaw config/state store. Calls are
+   * serialized in invocation order; each waits for the previous to settle. The
+   * caller's result (or rejection) is returned faithfully — a rejection does NOT
+   * poison the queue for the next caller.
+   */
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Promise-chain mutex. The tail is kept as a swallowed continuation so a rejected
+ * critical section never fails the NEXT unrelated caller, while the current caller
+ * still sees the real result/rejection.
+ */
+declare class SerialOpenClawCliLock implements OpenClawCliLock {
+  private tail;
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A lock that provides NO serialization — every `run` executes immediately. For
+ * runtimes/contexts with no concurrent-openclaw-writer hazard, and for tests that
+ * don't need serialization. Keeps consumers from having to special-case an absent
+ * lock.
+ */
+declare class NoopOpenClawCliLock implements OpenClawCliLock {
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+//#endregion
 //#region src/appliers/openclaw-applier.d.ts
 interface OpenClawApplierOptions {
   /**
@@ -771,6 +844,14 @@ interface OpenClawApplierOptions {
   configSetRetries?: number;
   /** Backoff between `openclaw config set` retries, ms (default 750; set 0 in tests) */
   configSetRetryDelayMs?: number;
+  /**
+   * Shared process-wide lock serializing ALL openclaw config/state-mutating CLI
+   * calls (this applier's + the gateway's mcp-cleanup / alfe.config_set). Inject
+   * the daemon's single instance so every openclaw mutation across BOTH packages
+   * queues behind one mutex. Defaults to a private `SerialOpenClawCliLock` so a
+   * standalone applier (and existing tests) still serialize their own writes.
+   */
+  cliLock?: OpenClawCliLock;
 }
 declare class OpenClawApplier implements RuntimeApplier {
   readonly runtime = "openclaw";
@@ -780,22 +861,38 @@ declare class OpenClawApplier implements RuntimeApplier {
   private trackingPath;
   private configSetRetries;
   private configSetRetryDelayMs;
-  /** Serializes all `openclaw config set` writes so they never interleave with each other or the hot-reload they trigger. */
-  private configSetQueue;
+  /**
+   * Shared process-wide mutex serializing ALL openclaw config/state-mutating CLI
+   * calls. Replaces the old per-applier `configSetQueue` promise-chain — a single
+   * lock so config-set can't interleave with plugins-install (or the gateway's
+   * mcp-cleanup / alfe.config_set), which is what corrupts the config store under
+   * OpenClaw's optimistic concurrency. NOT re-entrant: every locked public method
+   * acquires it ONCE at the top and calls only `*Unlocked` helpers inside.
+   */
+  private cliLock;
   constructor(options: OpenClawApplierOptions);
-  /** Convenience: `openclaw config set <args>`, serialized + retried. */
-  private runConfigSet;
   /**
-   * Run `openclaw config <args>` (set/unset), serialized against every other
-   * config write and retried with backoff. See CONFIG_SET_RETRIES for why:
-   * each write triggers a runtime hot-reload that rewrites openclaw.json, and a
-   * follow-up command that races the reload fails with a bare "Command failed".
+   * Convenience: `openclaw config set <args>`, UNLOCKED + retried.
+   *
+   * Assumes the shared CLI lock is already held by the calling public method.
+   * Never call this from outside a `cliLock.run(...)` section.
+   */
+  private runConfigSetUnlocked;
+  /**
+   * Run `openclaw config <args>` (set/unset), UNLOCKED, retried with backoff. See
+   * CONFIG_SET_RETRIES for why the retry loop exists: each write triggers a
+   * runtime hot-reload that rewrites openclaw.json, and a follow-up command that
+   * races the reload fails with a bare "Command failed".
+   *
+   * Serialization across every openclaw mutation is provided by `cliLock`, held
+   * by the public entry point — this helper assumes it and MUST NOT acquire the
+   * lock itself (that would deadlock the non-re-entrant promise-chain mutex).
    *
    * Throws an Error whose (scrubbed) message includes stderr after retries are
    * exhausted, so the real cause propagates to the integration errorMessage
    * without leaking the value payload.
    */
-  private runConfigCommand;
+  private runConfigCommandUnlocked;
   /**
    * Read back a single config path and compare it to the value we tried to
    * write. Used by `applyConfig`'s verify-after-write: a `config set` can exit
@@ -819,21 +916,30 @@ declare class OpenClawApplier implements RuntimeApplier {
   applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
   }): Promise<void>;
+  private applyPluginLocked;
   /**
-   * Ensure one or more plugins are in plugins.allow in openclaw.json.
+   * Ensure one or more plugins are in plugins.allow in openclaw.json, UNLOCKED.
    * Uses `openclaw config set` to avoid clobbering OpenClaw's own file format.
    *
+   * This is a read-modify-write (`config get plugins.allow` → union → `config
+   * set`). The caller MUST hold the shared CLI lock across the WHOLE call so no
+   * other openclaw process mutates `plugins.allow` between the read and the write
+   * (that would clobber the concurrent change). All callers wrap it in
+   * `cliLock.run(...)` — never invoke it outside a locked section.
+   *
    * Prefer passing the FULL set of plugins for an integration in a single call
    * (see `ensurePluginsAllowed`): each write triggers a runtime hot-reload, so
    * one write for N plugins is one reload instead of N.
    */
-  private ensurePluginsAllow;
+  private ensurePluginsAllowUnlocked;
   /**
    * Pre-trust every plugin an integration ships in a SINGLE plugins.allow
    * write, before any are installed. Called once by the manager ahead of the
    * per-plugin install loop so activation triggers one hot-reload for the
    * allowlist instead of one per plugin. `applyPlugin`'s own per-plugin
-   * `ensurePluginsAllow` then finds nothing missing and is a no-op.
+   * `ensurePluginsAllowUnlocked` then finds nothing missing and is a no-op.
+   *
+   * Acquires the shared CLI lock for the whole read-modify-write.
    */
   ensurePluginsAllowed(specs: string[]): Promise<void>;
   /**
@@ -845,6 +951,16 @@ declare class OpenClawApplier implements RuntimeApplier {
    * plugins under 2026.5+, which made force-mode skip its uninstall step.
    */
   private isPluginInstalled;
+  /**
+   * Best-effort read of the installed version of a plugin, or `undefined` when
+   * it can't be determined. Reads the version from the installed package's
+   * package.json under the npm registry path OpenClaw 2026.5+ installs to
+   * (`~/.openclaw/npm/node_modules/<pkg>/package.json`) — the same root
+   * `isPluginInstalled` checks. 2026.4 extensions-dir installs have no
+   * stable package.json version here and return `undefined` (callers fail
+   * open to the safe reinstall path).
+   */
+  private installedPluginVersion;
   /**
    * Remove an extensions/ install that has no matching record in
    * plugins/installs.json. OpenClaw 2026.5+ tracks installs via the records
@@ -856,6 +972,12 @@ declare class OpenClawApplier implements RuntimeApplier {
    */
   private cleanupUntrackedExtensionInstall;
   removePlugin(spec: string): Promise<void>;
+  /**
+   * `openclaw plugins uninstall`, UNLOCKED. Assumes the shared CLI lock is held
+   * by the caller (the public `removePlugin`, or `applyPluginLocked`'s force
+   * path). Never call outside a locked section.
+   */
+  private removePluginUnlocked;
   applySkill(name: string, srcPath: string): Promise<void>;
   applyClawHubSkill(slug: string): Promise<void>;
   removeClawHubSkill(slug: string): Promise<void>;
@@ -867,6 +989,7 @@ declare class OpenClawApplier implements RuntimeApplier {
    * (config.json) so it can be cleanly removed later.
    */
   applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
+  private applyConfigLocked;
   /**
    * Remove config previously applied by an integration.
    *
@@ -874,6 +997,7 @@ declare class OpenClawApplier implements RuntimeApplier {
    * then removes them via `openclaw config unset`.
    */
   removeConfig(integrationId: string): Promise<void>;
+  private removeConfigLocked;
   /**
    * Raw single-key config write — `openclaw config set <key> <value>`.
    *
@@ -1261,4 +1385,4 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   resetReinstallAttempts(integrationId: string): void;
 }
 //#endregion
-export { type CredentialsResolver, DEFAULT_REGISTRY_TTL_MS, HermesApplier, type HermesApplierOptions, HermesMcpSync, type HermesMcpSyncOptions, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, type McpStoreReader, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, type RegistryOptions, RegistryResolveError, type ResolveOptions, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeConfigEntry, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };
+export { type CredentialsResolver, DEFAULT_REGISTRY_TTL_MS, HermesApplier, type HermesApplierOptions, HermesMcpSync, type HermesMcpSyncOptions, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, type McpStoreReader, NoopOpenClawCliLock, OpenClawApplier, type OpenClawApplierOptions, type OpenClawCliLock, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, type RegistryOptions, RegistryResolveError, type ResolveOptions, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeConfigEntry, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, SerialOpenClawCliLock, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };

package/dist/index.js

@@ -856,6 +856,22 @@ function stripPluginVersion(spec) {
 	if (at <= 0) return spec;
 	return spec.slice(0, at);
 }
+/**
+* Return the pinned version from a plugin spec, or `undefined` when the spec
+* carries no version (bare package name). Mirror of `stripPluginVersion`: the
+* version is everything after the LAST '@' when that '@' sits at index > 0
+* (i.e. it's a real version delimiter, not the scope's leading '@').
+*
+* Used by the force-mode reinstall path to compare the pinned version against
+* the installed one so an already-current plugin can skip a ~45s
+* uninstall+reinstall cycle.
+*/
+function pluginSpecVersion(spec) {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return void 0;
+	const version = spec.slice(at + 1);
+	return version.length > 0 ? version : void 0;
+}
 //#endregion
 //#region src/integration-manager.ts
 /**
@@ -1617,6 +1633,32 @@ var IntegrationManager = class {
 	}
 };
 //#endregion
+//#region src/openclaw-cli-lock.ts
+/**
+* Promise-chain mutex. The tail is kept as a swallowed continuation so a rejected
+* critical section never fails the NEXT unrelated caller, while the current caller
+* still sees the real result/rejection.
+*/
+var SerialOpenClawCliLock = class {
+	tail = Promise.resolve();
+	run(fn) {
+		const result = this.tail.then(fn, fn);
+		this.tail = result.then(() => void 0, () => void 0);
+		return result;
+	}
+};
+/**
+* A lock that provides NO serialization — every `run` executes immediately. For
+* runtimes/contexts with no concurrent-openclaw-writer hazard, and for tests that
+* don't need serialization. Keeps consumers from having to special-case an absent
+* lock.
+*/
+var NoopOpenClawCliLock = class {
+	run(fn) {
+		return fn();
+	}
+};
+//#endregion
 //#region src/appliers/config-flatten.ts
 function flattenConfig(obj, prefix = "") {
 	const entries = [];
@@ -1703,6 +1745,15 @@ const BUNDLED_BASELINE_ALLOW = ["browser"];
 const CONFIG_SET_RETRIES$1 = 3;
 const CONFIG_SET_RETRY_DELAY_MS$1 = 750;
 /**
+* Max `openclaw config get` spawns in flight at once during the batch
+* verify-after-write. A naive `Promise.all(leaves.map(...))` fires one CLI
+* process per leaf simultaneously — a 36-leaf model-provider batch on a 2-vCPU
+* box means 36 concurrent `config get`s, each needing ~1.9s of CPU, so every
+* process blows its own 10s timeout and the verify reports false even when the
+* write actually landed. A small pool keeps the read-backs honest under load.
+*/
+const VERIFY_GET_CONCURRENCY = 4;
+/**
 * Sentinel OpenClaw returns from `config get` in place of a sensitive value —
 * the key IS set, OpenClaw is just hiding it. Verify-after-write must treat a
 * read-back of this as "present/matches" rather than a mismatch (see
@@ -1713,6 +1764,29 @@ const delay$1 = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 /**
+* Run `fn` over `items` with at most `limit` invocations in flight at once,
+* preserving result order. A tiny local pool (no new dependency) so the batch
+* verify-after-write doesn't stampede one `openclaw config get` per leaf — see
+* VERIFY_GET_CONCURRENCY.
+*
+* NOTE: relies on `fn` never rejecting (configValueMatches catches internally).
+* A throwing `fn` would reject the pool while sibling workers keep draining
+* items in the background — don't wire a throwing `fn` in here.
+*/
+async function mapWithConcurrency(items, limit, fn) {
+	const results = new Array(items.length);
+	let cursor = 0;
+	const worker = async () => {
+		while (cursor < items.length) {
+			const index = cursor++;
+			results[index] = await fn(items[index]);
+		}
+	};
+	const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+	await Promise.all(workers);
+	return results;
+}
+/**
 * Asymmetric structural containment for verify-after-write: is every field we
 * INTENDED present in the ACTUAL read-back with our value? `actual` may carry
 * EXTRA keys that `intended` does not.
@@ -1755,19 +1829,70 @@ function deepSubset(intended, actual) {
 function redactConfigSetTarget(args) {
 	return `openclaw config ${args.slice(0, 2).join(" ")}`.trim();
 }
+/** Cap a captured stream so a runaway OpenClaw dump can't bloat errorMessage. */
+const ERROR_STREAM_MAX = 400;
+function truncateForError(s) {
+	return s.length > ERROR_STREAM_MAX ? `${s.slice(0, ERROR_STREAM_MAX)}… (truncated)` : s;
+}
+/**
+* Collect the value strings a `config set` argv carries so they can be scrubbed
+* out of OpenClaw's own output. OpenClaw validation errors can echo the
+* offending VALUE back in their diagnostic text, so stdout/stderr must be
+* treated as value-bearing, not just the argv. For `{path, value}` batch
+* entries only the `value` side is collected — redacting the path out of
+* "invalid path models.providers…" would gut the diagnostic.
+*/
+function collectArgvValues(args) {
+	const out = [];
+	const collect = (v) => {
+		if (typeof v === "string") {
+			if (v.length >= 4) out.push(v);
+		} else if (Array.isArray(v)) v.forEach(collect);
+		else if (v !== null && typeof v === "object") {
+			const o = v;
+			if (typeof o.path === "string" && "value" in o) collect(o.value);
+			else Object.values(o).forEach(collect);
+		}
+	};
+	for (const token of args.slice(2)) {
+		if (token.startsWith("--")) continue;
+		try {
+			collect(JSON.parse(token));
+		} catch {
+			collect(token);
+		}
+	}
+	return out.sort((a, b) => b.length - a.length);
+}
+/** Replace every occurrence of the argv-derived values in a captured stream. */
+function scrubStream(s, values) {
+	let out = s;
+	for (const v of values) if (out.includes(v)) out = out.split(v).join("[REDACTED]");
+	return out;
+}
 /**
 * Build a diagnosable BUT scrubbed message from an execFile rejection. Node's
 * execFile error `message` is "Command failed: <full argv>" — which for
 * `config set` embeds the value payload — so we never surface it. We keep the
-* redacted target, the exit code, and `stderr` (openclaw's own error text).
+* redacted target, the exit code, `stderr`, and `stdout`.
+*
+* OpenClaw prints its own error text to STDOUT (not stderr), so on a genuine
+* failure `stderr` is often empty and the real cause is in stdout — surfacing
+* only stderr left days of bare "(exit 1)" in the logs. We include a truncated
+* stdout too — but scrubbed first: OpenClaw's error text can echo the offending
+* value, so both streams are run through `scrubStream` with the argv values
+* before anything reaches the dashboard-visible errorMessage.
 */
 function configSetErrorMessage(err, args) {
 	const target = redactConfigSetTarget(args);
 	if (err instanceof Error) {
 		const e = err;
-		const stderr = typeof e.stderr === "string" ? e.stderr.trim() : "";
+		const values = collectArgvValues(args);
+		const stderr = typeof e.stderr === "string" ? scrubStream(e.stderr.trim(), values) : "";
+		const stdout = typeof e.stdout === "string" ? scrubStream(e.stdout.trim(), values) : "";
 		const code = e.code !== void 0 ? ` (exit ${e.code})` : "";
-		return stderr ? `${target} failed${code}: ${stderr}` : `${target} failed${code}`;
+		const details = [stderr, stdout ? `stdout: ${truncateForError(stdout)}` : ""].filter(Boolean).join("; ");
+		return details ? `${target} failed${code}: ${details}` : `${target} failed${code}`;
 	}
 	return `${target} failed: ${String(err)}`;
 }
@@ -1791,8 +1916,15 @@ var OpenClawApplier = class {
 	trackingPath;
 	configSetRetries;
 	configSetRetryDelayMs;
-	/** Serializes all `openclaw config set` writes so they never interleave with each other or the hot-reload they trigger. */
-	configSetQueue = Promise.resolve();
+	/**
+	* Shared process-wide mutex serializing ALL openclaw config/state-mutating CLI
+	* calls. Replaces the old per-applier `configSetQueue` promise-chain — a single
+	* lock so config-set can't interleave with plugins-install (or the gateway's
+	* mcp-cleanup / alfe.config_set), which is what corrupts the config store under
+	* OpenClaw's optimistic concurrency. NOT re-entrant: every locked public method
+	* acquires it ONCE at the top and calls only `*Unlocked` helpers inside.
+	*/
+	cliLock;
 	constructor(options) {
 		const home = options.home ?? options.workspace;
 		if (!home) throw new Error("OpenClawApplier requires `home` (or legacy `workspace`) option");
@@ -1802,37 +1934,42 @@ var OpenClawApplier = class {
 		this.trackingPath = options.configPath ?? join(this.home, "config.json");
 		this.configSetRetries = options.configSetRetries ?? CONFIG_SET_RETRIES$1;
 		this.configSetRetryDelayMs = options.configSetRetryDelayMs ?? CONFIG_SET_RETRY_DELAY_MS$1;
+		this.cliLock = options.cliLock ?? new SerialOpenClawCliLock();
 	}
-	/** Convenience: `openclaw config set <args>`, serialized + retried. */
-	runConfigSet(setArgs, opts = {}) {
-		return this.runConfigCommand(["set", ...setArgs], opts);
+	/**
+	* Convenience: `openclaw config set <args>`, UNLOCKED + retried.
+	*
+	* Assumes the shared CLI lock is already held by the calling public method.
+	* Never call this from outside a `cliLock.run(...)` section.
+	*/
+	runConfigSetUnlocked(setArgs, opts = {}) {
+		return this.runConfigCommandUnlocked(["set", ...setArgs], opts);
 	}
 	/**
-	* Run `openclaw config <args>` (set/unset), serialized against every other
-	* config write and retried with backoff. See CONFIG_SET_RETRIES for why:
-	* each write triggers a runtime hot-reload that rewrites openclaw.json, and a
-	* follow-up command that races the reload fails with a bare "Command failed".
+	* Run `openclaw config <args>` (set/unset), UNLOCKED, retried with backoff. See
+	* CONFIG_SET_RETRIES for why the retry loop exists: each write triggers a
+	* runtime hot-reload that rewrites openclaw.json, and a follow-up command that
+	* races the reload fails with a bare "Command failed".
+	*
+	* Serialization across every openclaw mutation is provided by `cliLock`, held
+	* by the public entry point — this helper assumes it and MUST NOT acquire the
+	* lock itself (that would deadlock the non-re-entrant promise-chain mutex).
 	*
 	* Throws an Error whose (scrubbed) message includes stderr after retries are
 	* exhausted, so the real cause propagates to the integration errorMessage
 	* without leaking the value payload.
 	*/
-	runConfigCommand(args, opts = {}) {
+	async runConfigCommandUnlocked(args, opts = {}) {
 		const timeout = opts.timeout ?? 1e4;
-		const run = async () => {
-			let lastErr;
-			for (let attempt = 0; attempt <= this.configSetRetries; attempt++) try {
-				await execFileAsync$1("openclaw", ["config", ...args], { timeout });
-				return;
-			} catch (err) {
-				lastErr = err;
-				if (attempt < this.configSetRetries && this.configSetRetryDelayMs > 0) await delay$1(this.configSetRetryDelayMs * 2 ** attempt);
-			}
-			throw new Error(configSetErrorMessage(lastErr, args));
-		};
-		const result = this.configSetQueue.then(run, run);
-		this.configSetQueue = result.catch(() => void 0);
-		return result;
+		let lastErr;
+		for (let attempt = 0; attempt <= this.configSetRetries; attempt++) try {
+			await execFileAsync$1("openclaw", ["config", ...args], { timeout });
+			return;
+		} catch (err) {
+			lastErr = err;
+			if (attempt < this.configSetRetries && this.configSetRetryDelayMs > 0) await delay$1(this.configSetRetryDelayMs * 2 ** attempt);
+		}
+		throw new Error(configSetErrorMessage(lastErr, args));
 	}
 	/**
 	* Read back a single config path and compare it to the value we tried to
@@ -1873,17 +2010,32 @@ var OpenClawApplier = class {
 		}
 		return false;
 	}
-	async applyPlugin(spec, _installPath, opts) {
+	applyPlugin(spec, _installPath, opts) {
+		return this.cliLock.run(() => this.applyPluginLocked(spec, opts));
+	}
+	async applyPluginLocked(spec, opts) {
 		const pkg = stripPluginVersion(spec);
-		await this.ensurePluginsAllow(pkg);
+		await this.ensurePluginsAllowUnlocked(pkg);
 		this.cleanupUntrackedExtensionInstall(pkg);
 		if (opts?.force && this.isPluginInstalled(pkg)) {
+			const pinnedVersion = pluginSpecVersion(spec);
+			const installedVersion = this.installedPluginVersion(pkg);
+			if (pinnedVersion && installedVersion && installedVersion === pinnedVersion) {
+				log$3.info({
+					pkg,
+					spec,
+					version: installedVersion
+				}, "Force mode — installed version already matches pinned spec, skipping uninstall+reinstall");
+				return;
+			}
 			log$3.info({
 				pkg,
-				spec
+				spec,
+				installedVersion,
+				pinnedVersion
 			}, "Force mode — uninstalling plugin before reinstall");
 			try {
-				await this.removePlugin(pkg);
+				await this.removePluginUnlocked(pkg);
 			} catch (err) {
 				log$3.warn({
 					pkg,
@@ -1928,14 +2080,20 @@ var OpenClawApplier = class {
 		}
 	}
 	/**
-	* Ensure one or more plugins are in plugins.allow in openclaw.json.
+	* Ensure one or more plugins are in plugins.allow in openclaw.json, UNLOCKED.
 	* Uses `openclaw config set` to avoid clobbering OpenClaw's own file format.
 	*
+	* This is a read-modify-write (`config get plugins.allow` → union → `config
+	* set`). The caller MUST hold the shared CLI lock across the WHOLE call so no
+	* other openclaw process mutates `plugins.allow` between the read and the write
+	* (that would clobber the concurrent change). All callers wrap it in
+	* `cliLock.run(...)` — never invoke it outside a locked section.
+	*
 	* Prefer passing the FULL set of plugins for an integration in a single call
 	* (see `ensurePluginsAllowed`): each write triggers a runtime hot-reload, so
 	* one write for N plugins is one reload instead of N.
 	*/
-	async ensurePluginsAllow(pkgs) {
+	async ensurePluginsAllowUnlocked(pkgs) {
 		const wanted = Array.isArray(pkgs) ? pkgs : [pkgs];
 		let currentAllow = [];
 		try {
@@ -1951,7 +2109,7 @@ var OpenClawApplier = class {
 		if (missing.length === 0) return;
 		const updated = [...currentAllow, ...missing];
 		try {
-			await this.runConfigSet([
+			await this.runConfigSetUnlocked([
 				"plugins.allow",
 				JSON.stringify(updated),
 				"--merge"
@@ -1968,11 +2126,13 @@ var OpenClawApplier = class {
 	* write, before any are installed. Called once by the manager ahead of the
 	* per-plugin install loop so activation triggers one hot-reload for the
 	* allowlist instead of one per plugin. `applyPlugin`'s own per-plugin
-	* `ensurePluginsAllow` then finds nothing missing and is a no-op.
+	* `ensurePluginsAllowUnlocked` then finds nothing missing and is a no-op.
+	*
+	* Acquires the shared CLI lock for the whole read-modify-write.
 	*/
-	async ensurePluginsAllowed(specs) {
-		if (specs.length === 0) return;
-		await this.ensurePluginsAllow(specs.map(stripPluginVersion));
+	ensurePluginsAllowed(specs) {
+		if (specs.length === 0) return Promise.resolve();
+		return this.cliLock.run(() => this.ensurePluginsAllowUnlocked(specs.map(stripPluginVersion)));
 	}
 	/**
 	* Check if a plugin is already installed.
@@ -1990,6 +2150,25 @@ var OpenClawApplier = class {
 		return readdirSync(extensionsDir).some((dir) => dir.startsWith(prefix) && /^[0-9a-f]+$/i.test(dir.slice(prefix.length)));
 	}
 	/**
+	* Best-effort read of the installed version of a plugin, or `undefined` when
+	* it can't be determined. Reads the version from the installed package's
+	* package.json under the npm registry path OpenClaw 2026.5+ installs to
+	* (`~/.openclaw/npm/node_modules/<pkg>/package.json`) — the same root
+	* `isPluginInstalled` checks. 2026.4 extensions-dir installs have no
+	* stable package.json version here and return `undefined` (callers fail
+	* open to the safe reinstall path).
+	*/
+	installedPluginVersion(pkg) {
+		const pkgJsonPath = join(this.home, "npm", "node_modules", ...pkg.split("/"), "package.json");
+		if (!existsSync(pkgJsonPath)) return void 0;
+		try {
+			const data = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+			return typeof data.version === "string" ? data.version : void 0;
+		} catch {
+			return;
+		}
+	}
+	/**
 	* Remove an extensions/ install that has no matching record in
 	* plugins/installs.json. OpenClaw 2026.5+ tracks installs via the records
 	* file — a leftover dir from 2026.4 is invisible to `openclaw plugins
@@ -2034,7 +2213,15 @@ var OpenClawApplier = class {
 			}
 		}
 	}
-	async removePlugin(spec) {
+	removePlugin(spec) {
+		return this.cliLock.run(() => this.removePluginUnlocked(spec));
+	}
+	/**
+	* `openclaw plugins uninstall`, UNLOCKED. Assumes the shared CLI lock is held
+	* by the caller (the public `removePlugin`, or `applyPluginLocked`'s force
+	* path). Never call outside a locked section.
+	*/
+	async removePluginUnlocked(spec) {
 		await execFileAsync$1("openclaw", [
 			"plugins",
 			"uninstall",
@@ -2048,26 +2235,28 @@ var OpenClawApplier = class {
 		cpSync(srcPath, join(this.skillsDir, name), { recursive: true });
 		return Promise.resolve();
 	}
-	async applyClawHubSkill(slug) {
-		log$3.info({ slug }, "Installing skill from ClawHub");
-		try {
-			await execFileAsync$1("openclaw", [
-				"skills",
-				"install",
-				slug
-			], { timeout: 6e4 });
-			log$3.info({ slug }, "ClawHub skill installed");
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			if (msg.includes("already exists") || msg.includes("Skill already exists")) {
-				log$3.info({ slug }, "ClawHub skill already installed (skipped)");
-				return;
+	applyClawHubSkill(slug) {
+		return this.cliLock.run(async () => {
+			log$3.info({ slug }, "Installing skill from ClawHub");
+			try {
+				await execFileAsync$1("openclaw", [
+					"skills",
+					"install",
+					slug
+				], { timeout: 6e4 });
+				log$3.info({ slug }, "ClawHub skill installed");
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				if (msg.includes("already exists") || msg.includes("Skill already exists")) {
+					log$3.info({ slug }, "ClawHub skill already installed (skipped)");
+					return;
+				}
+				log$3.error({
+					slug,
+					err: msg
+				}, "ClawHub skill install failed");
 			}
-			log$3.error({
-				slug,
-				err: msg
-			}, "ClawHub skill install failed");
-		}
+		});
 	}
 	removeClawHubSkill(slug) {
 		const workspaceSkillsDir = join(this.agentWorkspace, "skills", slug);
@@ -2094,7 +2283,10 @@ var OpenClawApplier = class {
 	* Each integration's config contribution is tracked in the tracking file
 	* (config.json) so it can be cleanly removed later.
 	*/
-	async applyConfig(integrationId, config) {
+	applyConfig(integrationId, config) {
+		return this.cliLock.run(() => this.applyConfigLocked(integrationId, config));
+	}
+	async applyConfigLocked(integrationId, config) {
 		const tracking = this.readTracking();
 		const integrations = tracking._integrations ?? {};
 		integrations[integrationId] = config;
@@ -2105,7 +2297,7 @@ var OpenClawApplier = class {
 			const merged = { ...await readParentObject(parentPath) };
 			for (const [k, v] of dottedKvs) merged[k] = v;
 			try {
-				await this.runConfigSet([
+				await this.runConfigSetUnlocked([
 					parentPath,
 					JSON.stringify(merged),
 					"--merge"
@@ -2126,14 +2318,14 @@ var OpenClawApplier = class {
 			}
 		}
 		if (leaves.length > 0) try {
-			await this.runConfigSet([
+			await this.runConfigSetUnlocked([
 				"--batch-json",
 				JSON.stringify(leaves),
 				"--replace"
-			]);
+			], { timeout: Math.min(Math.max(3e4, leaves.length * 2e3), 12e4) });
 		} catch (err) {
 			if (await this.verifyApplied(async () => {
-				return (await Promise.all(leaves.map((l) => this.configValueMatches(l.path, l.value)))).every(Boolean);
+				return (await mapWithConcurrency(leaves, VERIFY_GET_CONCURRENCY, (l) => this.configValueMatches(l.path, l.value))).every(Boolean);
 			})) log$3.warn({ count: leaves.length }, "openclaw config set --batch-json exited non-zero but config landed — continuing");
 			else {
 				log$3.error({
@@ -2150,14 +2342,17 @@ var OpenClawApplier = class {
 	* Reads the tracking file to find which config keys this integration set,
 	* then removes them via `openclaw config unset`.
 	*/
-	async removeConfig(integrationId) {
+	removeConfig(integrationId) {
+		return this.cliLock.run(() => this.removeConfigLocked(integrationId));
+	}
+	async removeConfigLocked(integrationId) {
 		const tracking = this.readTracking();
 		const integrations = tracking._integrations ?? {};
 		if (!(integrationId in integrations)) return;
 		const integrationConfig = integrations[integrationId];
 		const { leaves, subtreesByParent } = partitionEntries(flattenConfig(integrationConfig));
 		for (const { path } of leaves) try {
-			await this.runConfigCommand(["unset", path]);
+			await this.runConfigCommandUnlocked(["unset", path]);
 		} catch (err) {
 			log$3.warn({
 				err: err instanceof Error ? err.message : String(err),
@@ -2169,8 +2364,8 @@ var OpenClawApplier = class {
 			const remaining = Object.fromEntries(Object.entries(existing).filter(([k]) => !dottedKvs.has(k)));
 			if (Object.keys(existing).length === 0) continue;
 			try {
-				if (Object.keys(remaining).length === 0) await this.runConfigCommand(["unset", parentPath]);
-				else await this.runConfigSet([
+				if (Object.keys(remaining).length === 0) await this.runConfigCommandUnlocked(["unset", parentPath]);
+				else await this.runConfigSetUnlocked([
 					parentPath,
 					JSON.stringify(remaining),
 					"--replace"
@@ -2196,7 +2391,7 @@ var OpenClawApplier = class {
 	* config writes trigger.
 	*/
 	setConfigRaw(key, value) {
-		return this.runConfigSet([key, value]);
+		return this.cliLock.run(() => this.runConfigSetUnlocked([key, value]));
 	}
 	isAvailable() {
 		return Promise.resolve(existsSync(this.home));
@@ -2948,4 +3143,4 @@ var IntegrationManagerAdapter = class {
 	}
 };
 //#endregion
-export { DEFAULT_REGISTRY_TTL_MS, HermesApplier, HermesMcpSync, Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };
+export { DEFAULT_REGISTRY_TTL_MS, HermesApplier, HermesMcpSync, Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, NoopOpenClawCliLock, OpenClawApplier, Registry, RegistryResolveError, Resolver, SerialOpenClawCliLock, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",