@karmaniverous/jeeves 0.6.0-1 → 0.6.0-2

package/README.md

@@ -227,9 +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`). Only that refusal is retried: 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.
+   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.
 
@@ -305,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}]
 ```
@@ -322,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.6.0-0` 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.6.0-0';
+const CORE_VERSION = '0.6.0-1';
 
 /**
  * Shared internal utility functions.
@@ -1639,7 +1639,9 @@ function configuredPluginIds(plugins, isJeeves) {
  * `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; any other failure is rethrown at once. Config writes are idempotent
+ * 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
@@ -1696,7 +1698,7 @@ function retryDelays(policy) {
  * still converging.
  *
  * @param action - The write.
- * @param options - Sleep, logger, policy.
+ * @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.
  */
@@ -1717,6 +1719,7 @@ async function withConvergenceRetry(action, options) {
                 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;
         }
@@ -1874,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
@@ -1918,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':
@@ -2146,8 +2202,9 @@ function createNodePrivateTempFiles(runner, platform = process.platform, baseDir
  * 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}); the batch file is kept for the retries
- * and deleted once.
+ * (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
  */
@@ -2155,6 +2212,7 @@ function createNodePrivateTempFiles(runner, platform = process.platform, baseDir
 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) {
@@ -2186,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);
@@ -3144,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.
@@ -3169,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.6.0-0` 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.6.0-0';
+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-1",
+  "version": "0.6.0-2",
   "allowScripts": {
     "lefthook": true
   }