@alfe.ai/integrations 0.2.7 → 0.2.8

package/dist/index.d.ts

@@ -870,6 +870,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 +918,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";
@@ -1760,6 +1760,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 +1963,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 +2006,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 +2053,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 +2191,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 +2358,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.8",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",