@karmaniverous/jeeves 0.6.0-1 → 0.6.0-3

package/README.md

@@ -226,10 +226,13 @@ 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.
+
+   Each plugin's config (`plugins.entries.<id>.config.<key>`: `configRoot`, `apiUrl`, the server `pluginKey`, and any other value the CLI resolves, see [Plugin config](#plugin-config)) is written **before** that plugin's install, with its own `openclaw config set --batch-file` call, and each install is followed by a migration sweep (see below). With a running gateway, `openclaw plugins install` activates the plugin at once, and the plugins read their config (e.g. `configRoot`) at registration: config written afterwards is too late, and a manifest default (the watcher's `configRoot`) would win. `plugins.entries` is also the only source CLI contexts such as `openclaw doctor --lint` see (they don't have `JEEVES_CONFIG_ROOT`). The order per plugin is config batch, install, sweep. Config for a plugin that is already installed at its version, and every value that is already set, is handled in step 4.
+
 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. Sets `plugins.entries.<id>.hooks.allowConversationAccess: true` for plugins that [declare conversation hooks](#declaring-conversation-hooks) (after the install: OpenClaw checks the installed package), plus the config of plugins that were not installed in this run, with one final `openclaw config set --batch-file <file>` call. When nothing was installed, a migration sweep (`openclaw plugins inspect --all --json`; its output is not shown and a failure is only logged) runs first. Every batch 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 a sweep runs `plugins inspect` right after each install. Every config batch (before an install and the final one) goes through the same retry: 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.
 
@@ -304,6 +307,7 @@ $ jeeves install watcher --dry-run
   @karmaniverous/jeeves-watcher-openclaw@0.16.0 (legacy copy found; conversation hooks: before_prompt_build)
 …
 [dry-run] openclaw plugins install npm:@karmaniverous/jeeves-watcher-openclaw@0.16.0 --pin --accept-capabilities --force
+[dry-run] openclaw plugins inspect --all --json (lets OpenClaw clear pending plugin migrations)
 [dry-run] remove legacy plugin copy: /home/jeeves/.openclaw/extensions/jeeves-watcher-openclaw
 [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}]
@@ -324,6 +328,10 @@ Plugin config:
 …
 [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>"}]
+[dry-run] openclaw plugins install npm:@karmaniverous/jeeves-server-openclaw@0.14.0 --pin --accept-capabilities --force
+[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.hooks.allowConversationAccess","value":true}]
 ```
 
 A live run stops at the first failing step. A non-zero exit from any `openclaw` or `npm` command makes `jeeves` exit 1 and print the command and its error output. Commands are spawned with an argument vector and no shell, so the same invocation works on Linux, macOS and Windows.

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-2` 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-2';
 
 /**
  * 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);
@@ -3124,7 +3185,9 @@ function installOptionsFromCli(opts, configRoot) {
  * install records, declared hooks, legacy directories) and then either
  * printed (`--dry-run`) or executed by {@link executePlan}. Step order encodes
  * the safety rules: legacy copies are removed only after the npm install
- * succeeded; config repair runs only after uninstall succeeded. Config writes
+ * succeeded; a plugin's config is written before its install (a running
+ * gateway activates it at once); config repair runs only after uninstall
+ * succeeded. Config writes
  * are `configSetBatch` steps, run as `openclaw config set --batch-file` with an
  * owner-only temp file, so no value (secret or not) is on a command line.
  *
@@ -3135,6 +3198,32 @@ const openclaw = (args) => ({
     command: OPENCLAW_BIN,
     args,
 });
+/** A config batch step (secrets attached for redaction when present). */
+const configBatch = (ops, secrets) => ({
+    kind: 'configSetBatch',
+    ops,
+    ...(secrets.length > 0 ? { redact: [...secrets] } : {}),
+});
+/**
+ * Split resolved config ops into per-plugin groups for the given plugin ids
+ * and the rest.
+ *
+ * @param ops - Resolved `plugins.entries.<id>.config.<key>` operations.
+ * @param pluginIds - Plugins whose config is written before their install.
+ * @returns Ops by plugin id, and the ops not claimed by any of them.
+ */
+function splitConfigOps(ops, pluginIds) {
+    const byPlugin = new Map();
+    const rest = [];
+    for (const op of ops) {
+        const owner = pluginIds.find((id) => op.path.startsWith(configValuePath(id, '')));
+        if (owner === undefined)
+            rest.push(op);
+        else
+            byPlugin.set(owner, [...(byPlugin.get(owner) ?? []), op]);
+    }
+    return { byPlugin, rest };
+}
 /**
  * Build the install/update plan.
  *
@@ -3142,20 +3231,33 @@ const openclaw = (args) => ({
  * @param plugins - Current `plugins` config slice.
  * @param config - Resolved plugin config to write (optional).
  * @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
- *   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.
+ *   there, e.g. a held lock, leaves OpenClaw untouched); then, per target not
+ *   yet installed at its version: a config batch with that plugin's resolved
+ *   `plugins.entries.<id>.config` values (when any need writing), the
+ *   `openclaw plugins install`, and a migration sweep. A running gateway
+ *   activates each plugin as soon as it is installed and plugins read their
+ *   config (e.g. `configRoot`) at registration, so the config must already
+ *   be there; it also overrides manifest defaults (e.g. the watcher's
+ *   `configRoot`). Then legacy removals, then one final batch (preceded by
+ *   a sweep when nothing was installed) with hook access (only for targets
+ *   that declare conversation hooks; OpenClaw checks the installed package)
+ *   and the config of already installed targets. Re-running after a later
+ *   failure converges: the server then has the key and the plugin side
+ *   copies it.
  */
 function buildInstallPlan(targets, plugins, config) {
     const steps = config?.serverKeyWrite
         ? [{ kind: 'serverKeyWrite', write: config.serverKeyWrite }]
         : [];
-    for (const t of targets) {
-        if (t.installed !== true) {
-            steps.push(openclaw(pluginInstallArgs(t.packageName, t.version)));
-        }
+    const secrets = config?.secrets ?? [];
+    const toInstall = targets.filter((t) => t.installed !== true);
+    const { byPlugin, rest } = splitConfigOps(config?.ops ?? [], toInstall.map((t) => t.pluginId));
+    for (const t of toInstall) {
+        const ops = byPlugin.get(t.pluginId);
+        if (ops)
+            steps.push(configBatch(ops, secrets));
+        steps.push(openclaw(pluginInstallArgs(t.packageName, t.version)));
+        steps.push({ kind: 'migrationSweep' });
     }
     for (const t of targets) {
         if (t.legacyDir)
@@ -3165,15 +3267,12 @@ function buildInstallPlan(targets, plugins, config) {
         ...computeHookAccessOps(plugins, targets
             .filter((t) => t.conversationHooks.length > 0)
             .map((t) => t.pluginId)),
-        ...(config?.ops ?? []),
+        ...rest,
     ];
     if (ops.length > 0) {
-        const secrets = config?.secrets ?? [];
-        steps.push({
-            kind: 'configSetBatch',
-            ops,
-            ...(secrets.length > 0 ? { redact: [...secrets] } : {}),
-        });
+        if (toInstall.length === 0)
+            steps.push({ kind: 'migrationSweep' });
+        steps.push(configBatch(ops, secrets));
     }
     return steps;
 }

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-2` 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-2';
 
 /**
  * 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-3",
   "allowScripts": {
     "lefthook": true
   }