@karmaniverous/jeeves 0.6.0-0 → 0.6.0-2

package/README.md

@@ -227,7 +227,9 @@ OpenClaw must already be installed; `jeeves` checks for it and never installs it
 1. Renders the SOUL.md/AGENTS.md managed blocks (your content outside the markers is kept) and the core config if it's missing. It never writes TOOLS.md, HEARTBEAT.md, anything under `skills/` or the spec templates (those ship with the jeeves-design skill in jeeves-tools).
 2. For each plugin (default: `runner`, `watcher`, `server`, `meta` at `latest`), resolves an exact version with `npm view`, then runs `openclaw plugins install npm:<pkg>@<version> --pin --accept-capabilities --force`. `--force` is required for any non-ClawHub source, and it also overwrites an existing install, which is how updates land. The install is skipped when that exact version is already installed. The CLI reads OpenClaw's install records once with `openclaw plugins inspect --all --json` (no plugin code is loaded) and skips a plugin only if its record has `source: "npm"`, names the same package, and records the same version, and the loaded plugin reports that version too. A v0.x path install, a leftover legacy copy, or any record it cannot read means a reinstall. `--force-reinstall` always reinstalls. Steps 3 and 4 run either way.
 3. Removes any legacy `<openclaw dir>/extensions/<id>` copy left by the v0.x installer, but only if its `package.json` names the expected package.
-4. Sets `plugins.entries.<id>.hooks.allowConversationAccess: true` for plugins that [declare conversation hooks](#declaring-conversation-hooks), and the plugin config (`plugins.entries.<id>.config.<key>`, see [Plugin config](#plugin-config)), with one `openclaw config set --batch-file <file>` call. The file is created owner-only in a fresh temp directory (mode `0600` in a `0700` directory on Linux/macOS; on Windows the directory ACL is reduced to the current user with `icacls`) and deleted afterwards, so no value, secret or not, appears on a command line. Every write targets a leaf path, so unrelated keys are kept. `plugins.installs` is never written.
+4. Runs `openclaw plugins inspect --all --json` once (a migration sweep, see below; its output is not shown and a failure is only logged), then sets `plugins.entries.<id>.hooks.allowConversationAccess: true` for plugins that [declare conversation hooks](#declaring-conversation-hooks), and the plugin config (`plugins.entries.<id>.config.<key>`, see [Plugin config](#plugin-config)), with one `openclaw config set --batch-file <file>` call. The file is created owner-only in a fresh temp directory (mode `0600` in a `0700` directory on Linux/macOS; on Windows the directory ACL is reduced to the current user with `icacls`) and deleted afterwards, so no value, secret or not, appears on a command line. Every write targets a leaf path, so unrelated keys are kept. `plugins.installs` is never written.
+
+   Right after an install, OpenClaw can refuse to edit a plugin's config until it finishes that plugin's data/settings upgrade (`Plugin "<id>" data/settings upgrade is unfinished: ... has not converged`). This happens when the gateway started with `plugins.entries.<id>` configured before the package was installed: OpenClaw records a pending migration for that plugin, installing it does not clear the record, and a refused `openclaw config set` doesn't either. OpenClaw resolves such records in the startup preflight of ordinary CLI commands (not `config`, and not `plugins list`), which is why the sweep runs `plugins inspect` before the batch. Only that refusal is retried: the sweep runs again, then the same batch file is resubmitted after 2s, 4s, 8s, 16s, then every 30s, for up to 120s of waiting in total, with one log line per retry. If the plugin still hasn't converged, the command fails and names the plugin; wait and rerun it (the writes are idempotent). Any other error fails at once. The `openclaw config unset` repairs after an uninstall follow the same rule. A dry run never retries.
 
 Plugin specs can be short (`watcher`, `watcher@1.2.3`, `runner@^1`) or full (`@karmaniverous/jeeves-watcher-openclaw@1.2.3`). Only `@karmaniverous/jeeves-*-openclaw` packages are accepted. `--content-only` skips the plugins.
 
@@ -303,6 +305,7 @@ $ jeeves install watcher --dry-run
 …
 [dry-run] openclaw plugins install npm:@karmaniverous/jeeves-watcher-openclaw@0.16.0 --pin --accept-capabilities --force
 [dry-run] remove legacy plugin copy: /home/jeeves/.openclaw/extensions/jeeves-watcher-openclaw
+[dry-run] openclaw plugins inspect --all --json (lets OpenClaw clear pending plugin migrations)
 [dry-run] openclaw config set --batch-file <private temp file>
 [dry-run]   batch file content: [{"path":"plugins.entries.jeeves-watcher-openclaw.hooks.allowConversationAccess","value":true}]
 ```
@@ -320,6 +323,7 @@ Plugin config:
 …
 [dry-run] set keys._plugin = <redacted> in /srv/jeeves/config/jeeves-server/config.json (currently unset; backup /srv/jeeves/config/jeeves-server/config.json.bak-<timestamp> first, then atomic write; restart jeeves-server afterwards)
 …
+[dry-run] openclaw plugins inspect --all --json (lets OpenClaw clear pending plugin migrations)
 [dry-run] openclaw config set --batch-file <private temp file>
 [dry-run]   batch file content: [{"path":"plugins.entries.jeeves-server-openclaw.config.configRoot","value":"/srv/jeeves/config"},{"path":"plugins.entries.jeeves-server-openclaw.config.apiUrl","value":"http://127.0.0.1:1934"},{"path":"plugins.entries.jeeves-server-openclaw.config.pluginKey","value":"<redacted>"}]
 ```

package/dist/cli/jeeves/index.js

@@ -140,14 +140,14 @@ const DEFAULT_PORTS = {
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.12` placeholder is replaced by
+ * The `0.6.0-1` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.5.12';
+const CORE_VERSION = '0.6.0-1';
 
 /**
  * Shared internal utility functions.
@@ -1626,6 +1626,106 @@ function configuredPluginIds(plugins, isJeeves) {
         .sort();
 }
 
+/**
+ * Retry OpenClaw config writes while freshly installed plugins converge.
+ *
+ * @remarks
+ * Right after `openclaw plugins install`, OpenClaw can refuse to edit a
+ * plugin's retained config until that plugin's deferred data/settings
+ * migration finishes. OpenClaw v2026.9.6 throws (from
+ * `src/config/deferred-plugin-migration-config.ts`, message built by
+ * `formatDeferredPluginMigration` in `src/infra/deferred-plugin-migrations.ts`):
+ *
+ * `Cannot edit retained config at "<path>". Plugin "<id>" data/settings upgrade is unfinished: <reason> ...`
+ *
+ * Only that signal is retried, with exponential backoff inside a fixed wait
+ * budget; before each wait the optional `beforeRetry` hook runs (the plan
+ * executor uses it to let OpenClaw clear pending migration records, see
+ * `migrationSweep.ts`, since a refused `config set` never clears them); any other failure is rethrown at once. Config writes are idempotent
+ * leaf sets/unsets, so repeating one is safe.
+ *
+ * @module
+ */
+/** Default policy: 2s, 4s, 8s, 16s, then 30s steps; 120s of waiting in total. */
+const DEFAULT_CONVERGENCE_RETRY = {
+    initialDelayMs: 2_000,
+    maxDelayMs: 30_000,
+    budgetMs: 120_000,
+};
+/** Default sleep adapter (real timer). */
+const timerSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const UNCONVERGED_PLUGIN = /Plugin "([^"]+)" data\/settings upgrade is unfinished/g;
+const UNCONVERGED_ANY = /upgrade is unfinished|has not converged/i;
+/**
+ * Detect OpenClaw's "plugin not yet converged" refusal in a failure.
+ *
+ * @param error - The thrown value.
+ * @returns The plugin ids still converging (`['unknown plugin']` when the
+ *   signal is present without an id), or `undefined` when this is some other
+ *   failure.
+ */
+function unconvergedPlugins(error) {
+    if (!(error instanceof CommandFailedError))
+        return undefined;
+    const text = `${error.result.stderr}\n${error.result.stdout}`;
+    if (!UNCONVERGED_ANY.test(text))
+        return undefined;
+    const ids = [
+        ...new Set([...text.matchAll(UNCONVERGED_PLUGIN)].map((m) => m[1])),
+    ];
+    return ids.length > 0 ? ids : ['unknown plugin'];
+}
+/**
+ * Delays for a policy: doubling from `initialDelayMs`, capped at
+ * `maxDelayMs`, until the next delay would exceed the budget.
+ *
+ * @param policy - Retry policy.
+ * @returns Delays in ms.
+ */
+function retryDelays(policy) {
+    const delays = [];
+    let total = 0;
+    let next = policy.initialDelayMs;
+    while (next > 0 && total + next <= policy.budgetMs) {
+        delays.push(next);
+        total += next;
+        next = Math.min(next * 2, policy.maxDelayMs);
+    }
+    return delays;
+}
+/**
+ * Run an idempotent OpenClaw config write, retrying only while plugins are
+ * still converging.
+ *
+ * @param action - The write.
+ * @param options - Sleep, logger, policy, pre-retry hook.
+ * @throws The original error for any other failure; an `Error` naming the
+ *   plugins still converging once the budget is spent.
+ */
+async function withConvergenceRetry(action, options) {
+    const delays = retryDelays(options.policy ?? DEFAULT_CONVERGENCE_RETRY);
+    let waited = 0;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await action();
+            return;
+        }
+        catch (error) {
+            const plugins = unconvergedPlugins(error);
+            if (!plugins)
+                throw error;
+            const delay = delays.at(attempt);
+            if (delay === undefined) {
+                throw new Error(`OpenClaw still refuses the config write after ${String(waited / 1000)}s: plugin(s) ${plugins.join(', ')} have not finished converging after install. Wait, then rerun the command (or run "openclaw doctor --fix").`, { cause: error });
+            }
+            options.log(`OpenClaw has not finished converging plugin(s) ${plugins.join(', ')}; retrying in ${String(delay / 1000)}s (retry ${String(attempt + 1)}/${String(delays.length)})`);
+            await options.beforeRetry?.();
+            await options.sleep(delay);
+            waited += delay;
+        }
+    }
+}
+
 /**
  * Pure builders for every `openclaw` / `npm` argument vector the jeeves CLI
  * runs. No I/O.
@@ -1777,6 +1877,57 @@ const npmViewVersionArgs = (packageName, range) => ['view', `${packageName}@${ra
  */
 const npmViewFieldArgs = (packageName, version, field) => ['view', `${packageName}@${version}`, field, '--json'];
 
+/**
+ * Let OpenClaw resolve pending plugin-migration records before config writes.
+ *
+ * @remarks
+ * When the gateway starts with `plugins.entries` for plugins that are not yet
+ * installed, OpenClaw records a pending (deferred) data/settings migration for
+ * each. Installing the plugin does not clear that record, and
+ * `openclaw config set` refuses to edit the plugin's retained config while it
+ * exists. `config` commands never clear it either: OpenClaw v2026.9.6 runs the
+ * startup state-migration preflight (`runDoctorConfigPreflight` with
+ * `migrateState: true`, which resolves finished records through
+ * `recordDeferredPluginMigrations`, see
+ * `src/commands/doctor-config-preflight-plugin-migrations.ts:160`) from
+ * `ensureConfigReady` (`src/cli/program/config-guard.ts:256-328`) for every
+ * guarded command except `config`, `health`, `logs`, `sessions` and a few
+ * others. `plugins list` skips the guard (`configGuard: "skip"`,
+ * `src/cli/command-catalog.ts:570-577`); `plugins inspect` has no catalog
+ * entry, so it takes the default `configGuard: "run"`
+ * (`src/cli/command-path-policy.ts:14`) and sweeps.
+ *
+ * The sweep is best effort: a failure is logged and never fails the plan (the
+ * config write that follows reports any real problem).
+ *
+ * @module
+ */
+/** Dry-run/log description of the sweep. */
+const MIGRATION_SWEEP_LINE = `${formatCommand(OPENCLAW_BIN, pluginsInspectAllArgs())} (lets OpenClaw clear pending plugin migrations)`;
+const warn = (log, reason) => {
+    log(`plugin migration sweep failed (continuing): ${reason}`);
+};
+/**
+ * Run `openclaw plugins inspect --all --json` so OpenClaw's startup preflight
+ * resolves pending plugin-migration records. Output is not echoed.
+ *
+ * @param runner - Command runner.
+ * @param log - Line logger.
+ */
+async function runMigrationSweep(runner, log) {
+    const args = pluginsInspectAllArgs();
+    log(`$ ${MIGRATION_SWEEP_LINE}`);
+    try {
+        const result = await runner(OPENCLAW_BIN, args);
+        if (result.exitCode !== 0) {
+            warn(log, describeExit(OPENCLAW_BIN, args, result.exitCode));
+        }
+    }
+    catch (error) {
+        warn(log, String(error));
+    }
+}
+
 /**
  * Human-readable lines for plan steps: the exact command lines, batch file
  * contents with secrets redacted, and conditional repairs. Pure; used for
@@ -1821,6 +1972,8 @@ function describeStep(step) {
             return [formatCommand(step.command, step.args)];
         case 'configSetBatch':
             return describeConfigBatchLines(step.ops, step.redact);
+        case 'migrationSweep':
+            return [MIGRATION_SWEEP_LINE];
         case 'removeDir':
             return [`remove legacy plugin copy: ${step.path}`];
         case 'serverKeyWrite':
@@ -2046,10 +2199,21 @@ function createNodePrivateTempFiles(runner, platform = process.platform, baseDir
  * Live: runs steps in order and stops at the first failure; a non-zero exit
  * from any `openclaw` command throws {@link CommandFailedError}, which the CLI
  * turns into a non-zero exit. Config batches are written to an owner-only
- * temp file, passed with `--batch-file`, and deleted afterwards.
+ * temp file, passed with `--batch-file`, and deleted afterwards. Config
+ * writes (batches and unsets) are retried with bounded backoff only while
+ * OpenClaw reports that a freshly installed plugin has not converged yet
+ * (see {@link withConvergenceRetry}); before each wait the migration sweep
+ * runs again (see {@link runMigrationSweep}), and the batch file is kept for
+ * the retries and deleted once.
  *
  * @module
  */
+/** Retry an idempotent config write while plugins converge. */
+const retryingConfigWrite = (ctx, action) => withConvergenceRetry(action, {
+    sleep: ctx.sleep ?? timerSleep,
+    log: ctx.log,
+    beforeRetry: () => runMigrationSweep(ctx.runner, ctx.log),
+});
 /** Run one command (echoing its output), logging its command line first. */
 async function runLogged(ctx, command, args) {
     ctx.log(`$ ${formatCommand(command, args)}`);
@@ -2067,12 +2231,9 @@ async function runConfigBatch(ctx, ops, redact) {
     ctx.log(`$ ${command}`);
     for (const line of details)
         ctx.log(line);
-    await withPrivateTempFile(ctx.tempFiles, BATCH_FILE_NAME, configBatchPayload(ops), async (path) => {
-        await runChecked(ctx.runner, OPENCLAW_BIN, configSetBatchFileArgs(path), {
-            echo: true,
-            ...(redact ? { redact } : {}),
-        });
-    }, ctx.log);
+    await withPrivateTempFile(ctx.tempFiles, BATCH_FILE_NAME, configBatchPayload(ops), (path) => retryingConfigWrite(ctx, async () => {
+        await runChecked(ctx.runner, OPENCLAW_BIN, configSetBatchFileArgs(path), { echo: true, ...(redact ? { redact } : {}) });
+    }), ctx.log);
 }
 /** Execute one step for real. */
 async function executeStep(step, ctx) {
@@ -2083,6 +2244,9 @@ async function executeStep(step, ctx) {
         case 'configSetBatch':
             await runConfigBatch(ctx, step.ops, step.redact);
             return;
+        case 'migrationSweep':
+            await runMigrationSweep(ctx.runner, ctx.log);
+            return;
         case 'removeDir':
             if (ctx.fs.isDirectory(step.path)) {
                 ctx.fs.removeDir(step.path);
@@ -2101,7 +2265,7 @@ async function executeStep(step, ctx) {
             const after = await readPluginsConfig(ctx.runner);
             const repair = computePostUninstallRepair(step.before, after, step.pluginIds);
             for (const path of repair.unsetPaths) {
-                await runLogged(ctx, OPENCLAW_BIN, configUnsetArgs(path));
+                await retryingConfigWrite(ctx, () => runLogged(ctx, OPENCLAW_BIN, configUnsetArgs(path)));
             }
             if (repair.setOps.length > 0)
                 await runConfigBatch(ctx, repair.setOps);
@@ -3041,6 +3205,8 @@ const openclaw = (args) => ({
  * @returns The server `keys._plugin` write (if planned; first, so a failure
  *   there, e.g. a held lock, leaves OpenClaw untouched), then install steps
  *   (targets not yet installed at their version), then legacy removals, then
+ *   (when there is config to write) a migration sweep so OpenClaw clears the
+ *   pending migration records it keeps for freshly installed plugins, then
  *   one config batch with hook access (only for targets that declare
  *   conversation hooks) and plugin config. Re-running after a later failure
  *   converges: the server then has the key and the plugin side copies it.
@@ -3066,6 +3232,7 @@ function buildInstallPlan(targets, plugins, config) {
     ];
     if (ops.length > 0) {
         const secrets = config?.secrets ?? [];
+        steps.push({ kind: 'migrationSweep' });
         steps.push({
             kind: 'configSetBatch',
             ops,

package/dist/index.js

@@ -142,14 +142,14 @@ const DEFAULT_PORTS = {
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.12` placeholder is replaced by
+ * The `0.6.0-1` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.5.12';
+const CORE_VERSION = '0.6.0-1';
 
 /**
  * Workspace and config root initialization.

package/package.json

@@ -133,7 +133,7 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.6.0-0",
+  "version": "0.6.0-2",
   "allowScripts": {
     "lefthook": true
   }