@alfe.ai/integrations 0.2.7 → 0.2.9

package/dist/index.d.ts

@@ -610,6 +610,15 @@ declare class IntegrationManager {
   clear(): void;
   private checkHealth;
   private err;
+  /**
+   * True when the manifest's `supported_agents` (if declared) intersects the
+   * registered runtime appliers. Hooks and MCP registration run once per
+   * integration (not per runtime), so they must use this aggregate check —
+   * the per-runtime loop's check only protects plugin/skill/config apply.
+   * The daemon registers exactly the agent's runtime, so checking the
+   * registered appliers' keys is sufficient.
+   */
+  private manifestSupportsRegisteredRuntime;
 }
 //#endregion
 //#region src/state.d.ts
@@ -699,6 +708,13 @@ interface HookEnvOptions {
   config?: Record<string, unknown>;
   /** Secret key-value pairs (in-memory only, injected as env vars) */
   secrets?: Map<string, unknown>;
+  /**
+   * Registered runtime name(s) on this agent (e.g. ["openclaw"]). Injected as
+   * ALFE_AGENT_RUNTIME so hooks can branch on runtime instead of sniffing for
+   * runtime binaries. The daemon registers exactly one runtime today; the
+   * value is comma-joined if that ever changes.
+   */
+  runtimes?: string[];
 }
 /**
  * Build the environment variables for a hook script execution.
@@ -706,6 +722,7 @@ interface HookEnvOptions {
  * Injects:
  * - ALFE_INTEGRATION_DIR=~/.alfe/integrations/{name}/
  * - ALFE_STATE_DIR=~/.alfe/state/{name}/ (creates dir if needed)
+ * - ALFE_AGENT_RUNTIME=openclaw (comma-joined registered runtime names)
  * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each config entry
  * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each secret entry
  */
@@ -870,6 +887,11 @@ declare class OpenClawApplier implements RuntimeApplier {
    * acquires it ONCE at the top and calls only `*Unlocked` helpers inside.
    */
   private cliLock;
+  /**
+   * Monotonic-ish guard for the state-DB self-heal — timestamp of the last heal
+   * this instance performed (0 = never). See HEAL_MIN_INTERVAL_MS.
+   */
+  private lastHealAt;
   constructor(options: OpenClawApplierOptions);
   /**
    * Convenience: `openclaw config set <args>`, UNLOCKED + retried.
@@ -913,6 +935,46 @@ declare class OpenClawApplier implements RuntimeApplier {
    * on the first success, false once all attempts are exhausted.
    */
   private verifyApplied;
+  /**
+   * `openclaw <args>` with automatic malformed-state-DB self-heal. On a
+   * malformed-DB failure (see isMalformedStateDbError): quarantine + recreate the
+   * state DB (healMalformedStateDb), then retry the ORIGINAL command exactly
+   * once. If the heal is rate-limited/failed, or the single retry also fails, the
+   * error propagates unchanged — callers keep their existing failure semantics
+   * (retry loops, install-tolerance checks, log.warn) as if healing never ran.
+   *
+   * Assumes the shared CLI lock is already held by the calling public method: the
+   * heal runs INSIDE the same locked section as the failed command. NEVER
+   * re-acquires the non-re-entrant `cliLock`.
+   *
+   * Runtime-alive safety: reconcile-path callers run under the gateway's
+   * RuntimeGate (runtime stopped), but the `setConfigRaw` hook (daemon
+   * `alfe.config_set`) can heal while `openclaw gateway run` still holds the DB.
+   * That is safe by fd/inode decoupling, not by exclusivity: renameSync is
+   * inode-level, the live runtime keeps writing its orphaned inode (discarded on
+   * its next restart — the state DB is disposable), and the recreated DB gets
+   * fresh -wal/-shm files the old process never attaches to.
+   */
+  private execOpenClawHealing;
+  /**
+   * Quarantine the corrupt OpenClaw state DB and recreate it. Never throws
+   * (logs + returns whether the heal succeeded). Rate-limited to one attempt per
+   * HEAL_MIN_INTERVAL_MS so a heal→re-corrupt→heal loop can't thrash the box.
+   *
+   * Steps (human-verified against a live managed agent): rename
+   * `state/openclaw.sqlite{,-wal,-shm}` aside with a `.quarantined-<ISO>` suffix
+   * (keep for forensics; -wal/-shm may be absent), then run `openclaw plugins
+   * list` to rebuild the DB via OpenClaw's migration framework (slow on a 2-vCPU
+   * box — 90s budget). Assumes the caller holds `cliLock` (see
+   * execOpenClawHealing for the runtime-alive rename semantics).
+   *
+   * A SUCCESSFUL heal consumes the full rate-limit window (a fresh DB exists for
+   * the runtime to re-corrupt — that loop is what the window prevents). A FAILED
+   * heal only gets the short cooldown: no fresh DB was produced, and a full
+   * window would strand the box with the main DB quarantined and no recreate for
+   * 10 minutes.
+   */
+  private healMalformedStateDb;
   applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
   }): Promise<void>;

package/dist/index.js

@@ -2,7 +2,7 @@ import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { basename, dirname, join } from "node:path";
 import { homedir, platform, tmpdir } from "node:os";
-import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { buildConfigValidationSchema, parseManifestFile } from "@alfe.ai/integration-manifest";
 import { createLogger } from "@auriclabs/logger";
 import { parseDocument } from "yaml";
@@ -671,11 +671,12 @@ const STATE_BASE_DIR = join(homedir(), ".alfe", "state");
 * Injects:
 * - ALFE_INTEGRATION_DIR=~/.alfe/integrations/{name}/
 * - ALFE_STATE_DIR=~/.alfe/state/{name}/ (creates dir if needed)
+* - ALFE_AGENT_RUNTIME=openclaw (comma-joined registered runtime names)
 * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each config entry
 * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each secret entry
 */
 function buildHookEnv(options, additionalEnv) {
-	const { integrationName, config, secrets } = options;
+	const { integrationName, config, secrets, runtimes } = options;
 	const nameUpper = integrationName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
 	const integrationDir = join(INTEGRATIONS_BASE_DIR, integrationName);
 	const stateDir = join(STATE_BASE_DIR, integrationName);
@@ -688,6 +689,7 @@ function buildHookEnv(options, additionalEnv) {
 		ALFE_INTEGRATION_DIR: integrationDir,
 		ALFE_STATE_DIR: stateDir
 	};
+	if (runtimes && runtimes.length > 0) env.ALFE_AGENT_RUNTIME = runtimes.join(",");
 	if (config) {
 		for (const [key, value] of Object.entries(config)) if (value !== void 0 && value !== null) {
 			const envKey = `ALFE_${nameUpper}_${key.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
@@ -1037,17 +1039,20 @@ var IntegrationManager = class {
 				const depState = this.state.get(dep);
 				if (!depState || depState.status === "error") throw new Error(`Dependency "${dep}" is not installed. Install it first: alfe integration install ${dep}`);
 			}
-			if (manifest.hooks.pre_install) {
+			const installHooksSupported = this.manifestSupportsRegisteredRuntime(manifest);
+			if (!installHooksSupported && (manifest.hooks.pre_install || manifest.hooks.post_install)) this.log.warn(`Integration "${name}" install hooks skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(manifest.supported_agents ?? []).join(", ")})`);
+			if (installHooksSupported && manifest.hooks.pre_install) {
 				this.log.info(`Running pre_install hook: ${manifest.hooks.pre_install}`);
 				const hookResult = await runHook(installPath, manifest.hooks.pre_install);
 				if (hookResult.exitCode !== 0) throw new Error(`pre_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
 			}
-			if (manifest.hooks.post_install) {
+			if (installHooksSupported && manifest.hooks.post_install) {
 				this.log.info(`Running post_install hook: ${manifest.hooks.post_install}`);
 				const hookResult = await runHookWithContext(installPath, manifest.hooks.post_install, {
 					integrationName: name,
 					config: config ?? {},
-					secrets: this.secrets.get(name)
+					secrets: this.secrets.get(name),
+					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) throw new Error(`post_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
 			}
@@ -1213,8 +1218,8 @@ var IntegrationManager = class {
 				if (appliedPlugins.length > 0 || skills.length > 0 || runtimeConfigApplied) this.lockManager.addEntries(runtimeName, integrationId, manifest.version, appliedPlugins, skills, installPath, { configApplied: runtimeConfigApplied });
 			}
 			const mcpServers = manifest.mcp_servers ?? [];
-			const runtimeSupportsMcp = !supportedAgents || supportedAgents.length === 0 || [...this.runtimeAppliers.keys()].some((r) => supportedAgents.includes(r));
-			if (mcpServers.length > 0 && !runtimeSupportsMcp) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${supportedAgents.join(", ")}) — skipping MCP registration`);
+			const runtimeSupported = this.manifestSupportsRegisteredRuntime(manifest);
+			if (mcpServers.length > 0 && !runtimeSupported) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(supportedAgents ?? []).join(", ")}) — skipping MCP registration`);
 			else if (mcpServers.length > 0) if (!this.mcpApplier) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no mcpApplier is wired — skipping MCP registration`);
 			else {
 				const secretEntries = this.secrets.get(integrationId);
@@ -1226,24 +1231,28 @@ var IntegrationManager = class {
 				await this.mcpApplier.applyForIntegration(integrationId, mcpServers, mergedConfig, { connectionId: entry.customConnectionId });
 			}
 			this.state.setStatus(integrationId, "active");
-			if (manifest.hooks.post_activate) {
+			if (manifest.hooks.post_activate && !runtimeSupported) this.log.warn(`Integration "${integrationId}" post_activate hook skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(supportedAgents ?? []).join(", ")})`);
+			else if (manifest.hooks.post_activate) {
 				this.log.info(`Running post_activate hook: ${manifest.hooks.post_activate}`);
 				const hookResult = await runHookWithContext(installPath, manifest.hooks.post_activate, {
 					integrationName: integrationId,
 					config: entry.config,
-					secrets: this.secrets.get(integrationId)
+					secrets: this.secrets.get(integrationId),
+					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) {
 					this.state.setStatus(integrationId, "error", `post_activate hook failed: ${hookResult.stderr || hookResult.stdout}`);
 					return this.err("POST_ACTIVATE_FAILED", `post_activate hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
 				}
 			}
-			if (manifest.hooks.health_check) {
+			if (manifest.hooks.health_check && !runtimeSupported) this.log.warn(`Integration "${integrationId}" health_check hook skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(supportedAgents ?? []).join(", ")})`);
+			else if (manifest.hooks.health_check) {
 				this.log.info(`Running health check: ${manifest.hooks.health_check}`);
 				const hookResult = await runHookWithContext(installPath, manifest.hooks.health_check, {
 					integrationName: integrationId,
 					config: entry.config,
-					secrets: this.secrets.get(integrationId)
+					secrets: this.secrets.get(integrationId),
+					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) {
 					this.state.setStatus(integrationId, "error", `Health check failed: ${hookResult.stderr || hookResult.stdout}`);
@@ -1386,21 +1395,25 @@ var IntegrationManager = class {
 			} catch {
 				this.log.warn(`Could not parse manifest for "${name}" — proceeding with basic cleanup`);
 			}
-			if (manifest?.hooks.pre_uninstall) {
+			const uninstallHooksSupported = manifest ? this.manifestSupportsRegisteredRuntime(manifest) : true;
+			if (manifest && !uninstallHooksSupported && (manifest.hooks.pre_uninstall || manifest.hooks.post_uninstall)) this.log.warn(`Integration "${name}" uninstall hooks skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(manifest.supported_agents ?? []).join(", ")})`);
+			if (uninstallHooksSupported && manifest?.hooks.pre_uninstall) {
 				this.log.info(`Running pre_uninstall hook: ${manifest.hooks.pre_uninstall}`);
 				const hookResult = await runHookWithContext(installPath, manifest.hooks.pre_uninstall, {
 					integrationName: name,
 					config: entry.config,
-					secrets: this.secrets.get(name)
+					secrets: this.secrets.get(name),
+					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) this.log.warn(`pre_uninstall hook failed (continuing): ${hookResult.stderr}`);
 			}
-			if (manifest?.hooks.post_uninstall) {
+			if (uninstallHooksSupported && manifest?.hooks.post_uninstall) {
 				this.log.info(`Running post_uninstall hook: ${manifest.hooks.post_uninstall}`);
 				const hookResult = await runHookWithContext(installPath, manifest.hooks.post_uninstall, {
 					integrationName: name,
 					config: entry.config,
-					secrets: this.secrets.get(name)
+					secrets: this.secrets.get(name),
+					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) this.log.warn(`post_uninstall hook failed (non-fatal): ${hookResult.stderr}`);
 			}
@@ -1597,10 +1610,19 @@ var IntegrationManager = class {
 				version: manifest.version,
 				message: "No health check hook defined"
 			};
+			if (!this.manifestSupportsRegisteredRuntime(manifest)) return {
+				id,
+				name: manifest.name,
+				healthy: entry.status === "active" || entry.status === "configured" || entry.status === "installed",
+				status: entry.status,
+				version: manifest.version,
+				message: "Health check hook skipped — integration does not support this agent runtime"
+			};
 			const hookResult = await runHookWithContext(installPath, manifest.hooks.health_check, {
 				integrationName: id,
 				config: entry.config,
-				secrets: this.secrets.get(id)
+				secrets: this.secrets.get(id),
+				runtimes: [...this.runtimeAppliers.keys()]
 			});
 			return {
 				id,
@@ -1631,6 +1653,18 @@ var IntegrationManager = class {
 			}
 		};
 	}
+	/**
+	* True when the manifest's `supported_agents` (if declared) intersects the
+	* registered runtime appliers. Hooks and MCP registration run once per
+	* integration (not per runtime), so they must use this aggregate check —
+	* the per-runtime loop's check only protects plugin/skill/config apply.
+	* The daemon registers exactly the agent's runtime, so checking the
+	* registered appliers' keys is sufficient.
+	*/
+	manifestSupportsRegisteredRuntime(manifest) {
+		const supported = manifest.supported_agents;
+		return !supported || supported.length === 0 || [...this.runtimeAppliers.keys()].some((r) => supported.includes(r));
+	}
 };
 //#endregion
 //#region src/openclaw-cli-lock.ts
@@ -1760,6 +1794,44 @@ const VERIFY_GET_CONCURRENCY = 4;
 * `configValueMatches`).
 */
 const OPENCLAW_REDACTED = "__OPENCLAW_REDACTED__";
+/**
+* OpenClaw's gateway runtime deterministically truncates its own WAL-mode state
+* DB (`<home>/state/openclaw.sqlite`) ~50s after boot: the page_count header
+* shrinks while btree/freelist entries still reference pages past the new end.
+* Once corrupt, EVERY `openclaw` CLI invocation that walks the freelist dies at
+* startup with this exact phrase (printed to STDOUT, exit 1), which kills every
+* `plugins install` during activation. Upstream (no fix, suggests exactly this
+* quarantine-and-recreate recovery): https://github.com/openclaw/openclaw/issues/71689.
+* `doctor --fix` does NOT detect it. The state DB is disposable — plugin installs
+* live in `<home>/npm/node_modules` + the on-disk registry, so quarantine + any
+* CLI command rebuilds it via migrations with no meaningful loss.
+*/
+const MALFORMED_STATE_DB_PHRASE = "database disk image is malformed";
+/**
+* Rate-limit the state-DB self-heal to ONE attempt per applier instance per
+* window so a heal→corrupt→heal loop (the runtime re-corrupts the fresh DB ~50s
+* later) can't thrash the box. Wall-clock `Date.now()` is fine here — this is
+* runtime daemon code, not a workflow script.
+*/
+const HEAL_MIN_INTERVAL_MS = 600 * 1e3;
+/**
+* Cooldown after a FAILED heal attempt. A failed heal produced no fresh DB, so
+* the full HEAL_MIN_INTERVAL_MS lockout is unjustified (it would strand the box
+* with the main DB quarantined and no recreate); a short cooldown just stops a
+* tight retry loop from hammering rename/recreate.
+*/
+const FAILED_HEAL_COOLDOWN_MS = 60 * 1e3;
+/**
+* True when an execFile rejection carries the malformed-state-DB signature.
+* OpenClaw prints the reason to STDOUT (not stderr), and Node's execFile error
+* embeds the argv in `message`, so all three streams are checked. The phrase is
+* specific enough to match on directly (case-insensitive).
+*/
+function isMalformedStateDbError(err) {
+	if (!(err instanceof Error)) return false;
+	const e = err;
+	return `${e.message}\n${e.stderr ?? ""}\n${e.stdout ?? ""}`.toLowerCase().includes(MALFORMED_STATE_DB_PHRASE);
+}
 const delay$1 = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
@@ -1925,6 +1997,11 @@ var OpenClawApplier = class {
 	* acquires it ONCE at the top and calls only `*Unlocked` helpers inside.
 	*/
 	cliLock;
+	/**
+	* Monotonic-ish guard for the state-DB self-heal — timestamp of the last heal
+	* this instance performed (0 = never). See HEAL_MIN_INTERVAL_MS.
+	*/
+	lastHealAt = 0;
 	constructor(options) {
 		const home = options.home ?? options.workspace;
 		if (!home) throw new Error("OpenClawApplier requires `home` (or legacy `workspace`) option");
@@ -1963,7 +2040,7 @@ var OpenClawApplier = class {
 		const timeout = opts.timeout ?? 1e4;
 		let lastErr;
 		for (let attempt = 0; attempt <= this.configSetRetries; attempt++) try {
-			await execFileAsync$1("openclaw", ["config", ...args], { timeout });
+			await this.execOpenClawHealing(["config", ...args], { timeout });
 			return;
 		} catch (err) {
 			lastErr = err;
@@ -2010,6 +2087,99 @@ var OpenClawApplier = class {
 		}
 		return false;
 	}
+	/**
+	* `openclaw <args>` with automatic malformed-state-DB self-heal. On a
+	* malformed-DB failure (see isMalformedStateDbError): quarantine + recreate the
+	* state DB (healMalformedStateDb), then retry the ORIGINAL command exactly
+	* once. If the heal is rate-limited/failed, or the single retry also fails, the
+	* error propagates unchanged — callers keep their existing failure semantics
+	* (retry loops, install-tolerance checks, log.warn) as if healing never ran.
+	*
+	* Assumes the shared CLI lock is already held by the calling public method: the
+	* heal runs INSIDE the same locked section as the failed command. NEVER
+	* re-acquires the non-re-entrant `cliLock`.
+	*
+	* Runtime-alive safety: reconcile-path callers run under the gateway's
+	* RuntimeGate (runtime stopped), but the `setConfigRaw` hook (daemon
+	* `alfe.config_set`) can heal while `openclaw gateway run` still holds the DB.
+	* That is safe by fd/inode decoupling, not by exclusivity: renameSync is
+	* inode-level, the live runtime keeps writing its orphaned inode (discarded on
+	* its next restart — the state DB is disposable), and the recreated DB gets
+	* fresh -wal/-shm files the old process never attaches to.
+	*/
+	async execOpenClawHealing(args, opts = {}) {
+		try {
+			await execFileAsync$1("openclaw", args, opts);
+			return;
+		} catch (err) {
+			if (!isMalformedStateDbError(err)) throw err;
+			log$3.warn({ args: args.slice(0, 2) }, "openclaw CLI failed with a malformed state DB — attempting self-heal then one retry");
+			if (!await this.healMalformedStateDb()) throw err;
+			await execFileAsync$1("openclaw", args, opts);
+		}
+	}
+	/**
+	* Quarantine the corrupt OpenClaw state DB and recreate it. Never throws
+	* (logs + returns whether the heal succeeded). Rate-limited to one attempt per
+	* HEAL_MIN_INTERVAL_MS so a heal→re-corrupt→heal loop can't thrash the box.
+	*
+	* Steps (human-verified against a live managed agent): rename
+	* `state/openclaw.sqlite{,-wal,-shm}` aside with a `.quarantined-<ISO>` suffix
+	* (keep for forensics; -wal/-shm may be absent), then run `openclaw plugins
+	* list` to rebuild the DB via OpenClaw's migration framework (slow on a 2-vCPU
+	* box — 90s budget). Assumes the caller holds `cliLock` (see
+	* execOpenClawHealing for the runtime-alive rename semantics).
+	*
+	* A SUCCESSFUL heal consumes the full rate-limit window (a fresh DB exists for
+	* the runtime to re-corrupt — that loop is what the window prevents). A FAILED
+	* heal only gets the short cooldown: no fresh DB was produced, and a full
+	* window would strand the box with the main DB quarantined and no recreate for
+	* 10 minutes.
+	*/
+	async healMalformedStateDb() {
+		const now = Date.now();
+		if (now - this.lastHealAt < HEAL_MIN_INTERVAL_MS) {
+			log$3.warn({ sinceLastHealMs: now - this.lastHealAt }, "openclaw state DB malformed but a heal ran within the rate-limit window — skipping to avoid a heal→corrupt→heal loop");
+			return false;
+		}
+		this.lastHealAt = now;
+		const stateDir = join(this.home, "state");
+		const stamp = new Date(now).toISOString().replaceAll(":", "-");
+		const quarantined = [];
+		try {
+			for (const name of [
+				"openclaw.sqlite",
+				"openclaw.sqlite-wal",
+				"openclaw.sqlite-shm"
+			]) {
+				const src = join(stateDir, name);
+				if (!existsSync(src)) continue;
+				const dest = `${src}.quarantined-${stamp}`;
+				renameSync(src, dest);
+				quarantined.push(dest);
+			}
+			if (quarantined.length === 0) {
+				log$3.warn({ stateDir }, "malformed openclaw state DB reported but no state/openclaw.sqlite* files found to quarantine");
+				this.lastHealAt = now - HEAL_MIN_INTERVAL_MS + FAILED_HEAL_COOLDOWN_MS;
+				return false;
+			}
+			log$3.warn({
+				stateDir,
+				quarantined
+			}, "quarantined malformed openclaw state DB — recreating via `openclaw plugins list` (upstream openclaw/openclaw#71689)");
+			await execFileAsync$1("openclaw", ["plugins", "list"], { timeout: 9e4 });
+			log$3.warn({ stateDir }, "recreated openclaw state DB after quarantine");
+			return true;
+		} catch (err) {
+			log$3.warn({
+				stateDir,
+				quarantined,
+				err: err instanceof Error ? err.message : String(err)
+			}, "failed to heal malformed openclaw state DB — leaving quarantined files for forensics");
+			this.lastHealAt = now - HEAL_MIN_INTERVAL_MS + FAILED_HEAL_COOLDOWN_MS;
+			return false;
+		}
+	}
 	applyPlugin(spec, _installPath, opts) {
 		return this.cliLock.run(() => this.applyPluginLocked(spec, opts));
 	}
@@ -2055,12 +2225,12 @@ var OpenClawApplier = class {
 			const args = useUnsafeFlag ? [...baseArgs, "--dangerously-force-unsafe-install"] : baseArgs;
 			try {
 				try {
-					await execFileAsync$1("openclaw", args, { timeout: 6e4 });
+					await this.execOpenClawHealing(args, { timeout: 6e4 });
 				} catch (err) {
 					const errText = err instanceof Error ? `${err.message}\n${err.stderr ?? ""}` : String(err);
 					if (useUnsafeFlag && errText.includes("unknown option")) {
 						log$3.info({ pkg }, "OpenClaw does not support --dangerously-force-unsafe-install, retrying without");
-						await execFileAsync$1("openclaw", baseArgs, { timeout: 6e4 });
+						await this.execOpenClawHealing(baseArgs, { timeout: 6e4 });
 					} else throw err;
 				}
 			} catch (err) {
@@ -2222,11 +2392,12 @@ var OpenClawApplier = class {
 	* path). Never call outside a locked section.
 	*/
 	async removePluginUnlocked(spec) {
-		await execFileAsync$1("openclaw", [
+		const pkg = stripPluginVersion(spec);
+		await this.execOpenClawHealing([
 			"plugins",
 			"uninstall",
 			"--force",
-			stripPluginVersion(spec)
+			pkg
 		], { timeout: 3e4 });
 	}
 	applySkill(name, srcPath) {

package/package.json

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