fix(update): narrow corrupt plugin warnings

steipete · steipete · commit c4258010ded7 · 2026-05-05T08:24:55.000+01:00
diff --git a/docs/cli/update.md b/docs/cli/update.md
@@ -38,8 +38,9 @@ openclaw --update
 - `--tag <dist-tag|version|spec>`: override the package target for this update only. For package installs, `main` maps to `github:openclaw/openclaw#main`.
 - `--dry-run`: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
 - `--json`: print machine-readable `UpdateRunResult` JSON, including
-  `postUpdate.plugins.integrityDrifts` when npm plugin artifact drift is
-  detected during post-update plugin sync.
+  `postUpdate.plugins.warnings` when corrupt or unloadable managed plugins need
+  repair after the core update succeeds, and `postUpdate.plugins.integrityDrifts`
+  when npm plugin artifact drift is detected during post-update plugin sync.
 - `--timeout <seconds>`: per-step timeout (default is 1800s).
 - `--yes`: skip confirmation prompts (for example downgrade confirmation).
 
@@ -177,7 +178,7 @@ If an exact pinned npm plugin update resolves to an artifact whose integrity dif
 </Warning>
 
 <Note>
-Post-update plugin sync failures fail the update result and stop restart follow-up work. Fix the plugin install or update error, then rerun `openclaw update`.
+Post-update plugin sync failures that are scoped to a managed plugin are reported as warnings after the core update succeeds. The JSON result keeps the top-level update `status: "ok"` and reports `postUpdate.plugins.status: "warning"` with `openclaw doctor --fix` and `openclaw plugins inspect <id> --runtime --json` guidance. Unexpected updater or sync exceptions still fail the update result. Fix the plugin install or update error, then rerun `openclaw doctor --fix` or `openclaw update`.
 
 When the updated Gateway starts, plugin loading is verify-only: startup does not run package managers or mutate dependency trees. Package-manager `update.run` restarts bypass the normal idle deferral and restart cooldown after the package tree has been swapped, so the old process cannot keep lazy-loading removed chunks.
 
diff --git a/docs/help/testing-updates-plugins.md b/docs/help/testing-updates-plugins.md
@@ -172,7 +172,7 @@ targets the shipped npm package instead.
 Release checks call Package Acceptance with the package/update/restart/plugin set:
 
 ```text
-doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update
+doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update
 ```
 
 When release soak is enabled, they also pass:
@@ -183,10 +183,10 @@ published_upgrade_survivor_scenarios=reported-issues
 telegram_mode=mock-openai
 ```
 
-This keeps package migration, update channel switching, stale plugin dependency
-cleanup, offline plugin coverage, plugin update behavior, and Telegram package
-QA on the same resolved artifact without making the default release package gate
-walk every published release.
+This keeps package migration, update channel switching, corrupt managed-plugin
+tolerance, stale plugin dependency cleanup, offline plugin coverage, plugin
+update behavior, and Telegram package QA on the same resolved artifact without
+making the default release package gate walk every published release.
 
 `last-stable-4` resolves to the four latest stable npm-published OpenClaw
 releases. Release package acceptance pins `2026.4.23` as the first plugin-update
diff --git a/scripts/e2e/lib/plugin-update/probe.mjs b/scripts/e2e/lib/plugin-update/probe.mjs
@@ -121,16 +121,20 @@ function assertCorruptUpdate(updateJsonPath, pluginId) {
   if (!plugins) {
     throw new Error(`missing postUpdate.plugins in update output: ${JSON.stringify(payload)}`);
   }
-  if (plugins.status !== "ok") {
-    throw new Error(`expected post-update plugin status ok, got ${JSON.stringify(plugins.status)}`);
+  if (plugins.status !== "warning") {
+    throw new Error(
+      `expected post-update plugin status warning, got ${JSON.stringify(plugins.status)}`,
+    );
   }
   assertCorruptPluginDetails(plugins, pluginId);
 }
 
 function assertCorruptPluginResult(pluginJsonPath, pluginId) {
   const plugins = readJson(pluginJsonPath);
-  if (plugins.status !== "ok") {
-    throw new Error(`expected post-update plugin status ok, got ${JSON.stringify(plugins.status)}`);
+  if (plugins.status !== "warning") {
+    throw new Error(
+      `expected post-update plugin status warning, got ${JSON.stringify(plugins.status)}`,
+    );
   }
   assertCorruptPluginDetails(plugins, pluginId);
 }
diff --git a/src/cli/update-cli.test.ts b/src/cli/update-cli.test.ts
@@ -1039,7 +1039,7 @@ describe("update-cli", () => {
         action: "aborted",
       },
     ]);
-    expect(jsonOutput?.postUpdate?.plugins?.status).toBe("ok");
+    expect(jsonOutput?.postUpdate?.plugins?.status).toBe("warning");
     expect(jsonOutput?.postUpdate?.plugins?.warnings?.[0]).toMatchObject({
       pluginId: "demo",
       guidance: [
@@ -1107,7 +1107,7 @@ describe("update-cli", () => {
       | UpdateRunResult
       | undefined;
     expect(jsonOutput?.status).toBe("ok");
-    expect(jsonOutput?.postUpdate?.plugins?.status).toBe("ok");
+    expect(jsonOutput?.postUpdate?.plugins?.status).toBe("warning");
     expect(jsonOutput?.postUpdate?.plugins?.warnings?.[0]).toMatchObject({
       pluginId: "demo",
     });
@@ -1154,6 +1154,22 @@ describe("update-cli", () => {
     expect(logs).toContain("Run openclaw plugins inspect demo --runtime --json for details.");
   });
 
+  it("fails unexpected post-core plugin sync exceptions", async () => {
+    syncPluginsForUpdateChannel.mockRejectedValueOnce(new Error("plugin sync invariant broke"));
+
+    await expect(updateCommand({ json: true, restart: false })).rejects.toThrow(
+      "plugin sync invariant broke",
+    );
+  });
+
+  it("fails unexpected post-core npm update exceptions", async () => {
+    updateNpmInstalledPlugins.mockRejectedValueOnce(new Error("npm update invariant broke"));
+
+    await expect(updateCommand({ json: true, restart: false })).rejects.toThrow(
+      "npm update invariant broke",
+    );
+  });
+
   it("preserves fresh-process plugin warning details in parent json output", async () => {
     setupUpdatedRootRefresh();
     spawn.mockImplementationOnce((_node, _argv, options) => {
@@ -1167,7 +1183,7 @@ describe("update-cli", () => {
           await fs.writeFile(
             resultPath,
             JSON.stringify({
-              status: "ok",
+              status: "warning",
               changed: false,
               warnings: [
                 {
diff --git a/src/cli/update-cli/update-command.ts b/src/cli/update-cli/update-command.ts
@@ -266,21 +266,23 @@ function createPostUpdatePluginWarning(params: {
   };
 }
 
-function addPostUpdatePluginGuidance(outcome: PluginUpdateOutcome): PluginUpdateOutcome {
+function createGuidedPostUpdatePluginOutcome(outcome: PluginUpdateOutcome): {
+  outcome: PluginUpdateOutcome;
+  warning?: PostUpdatePluginWarning;
+} {
   if (outcome.status !== "error") {
-    return outcome;
-  }
-  const guidance = [
-    POST_UPDATE_PLUGIN_REPAIR_GUIDANCE,
-    formatPostUpdatePluginInspectGuidance(outcome.pluginId),
-  ];
-  const missing = guidance.filter((entry) => !outcome.message.includes(entry));
-  if (missing.length === 0) {
-    return outcome;
+    return { outcome };
   }
+  const warning = createPostUpdatePluginWarning({
+    ...(outcome.pluginId && outcome.pluginId !== "unknown" ? { pluginId: outcome.pluginId } : {}),
+    reason: outcome.message,
+  });
   return {
-    ...outcome,
-    message: `${outcome.message} ${missing.join(" ")}`,
+    outcome: {
+      ...outcome,
+      message: warning.message,
+    },
+    warning,
   };
 }
 
@@ -1125,25 +1127,6 @@ async function updatePluginsAfterCoreUpdate(params: {
       workspaceDir: params.root,
     }),
     logger: pluginLogger,
-  }).catch((error: unknown) => {
-    const warning = createPostUpdatePluginWarning({
-      reason: error instanceof Error ? error.message : String(error),
-    });
-    warnings.push(warning);
-    if (!params.opts.json) {
-      defaultRuntime.log(theme.warn(warning.message));
-    }
-    return {
-      config: syncConfig,
-      changed: false,
-      summary: {
-        switchedToBundled: [],
-        switchedToClawHub: [],
-        switchedToNpm: [],
-        warnings: [warning.message],
-        errors: [],
-      },
-    };
   });
   for (const error of syncResult.summary.errors) {
     warnings.push(createPostUpdatePluginWarning({ reason: error }));
@@ -1218,41 +1201,16 @@ async function updatePluginsAfterCoreUpdate(params: {
     skipDisabledPlugins: true,
     logger: pluginLogger,
     onIntegrityDrift: onPluginIntegrityDrift,
-  }).catch((error: unknown) => {
-    const warning = createPostUpdatePluginWarning({
-      reason: error instanceof Error ? error.message : String(error),
-    });
-    warnings.push(warning);
-    if (!params.opts.json) {
-      defaultRuntime.log(theme.warn(warning.message));
-    }
-    return {
-      config: pluginConfig,
-      changed: false,
-      outcomes: [
-        {
-          pluginId: "unknown",
-          status: "error" as const,
-          message: warning.message,
-        },
-      ],
-    };
   });
   pluginConfig = npmResult.config;
   pluginsChanged ||= npmResult.changed;
   npmPluginsChanged ||= npmResult.changed;
-  const guidedNpmOutcomes = npmResult.outcomes.map(addPostUpdatePluginGuidance);
-  pluginUpdateOutcomes.push(...guidedNpmOutcomes);
-  for (const outcome of guidedNpmOutcomes) {
-    if (outcome.status !== "error") {
-      continue;
+  for (const rawOutcome of npmResult.outcomes) {
+    const guided = createGuidedPostUpdatePluginOutcome(rawOutcome);
+    pluginUpdateOutcomes.push(guided.outcome);
+    if (guided.warning) {
+      warnings.push(guided.warning);
     }
-    warnings.push(
-      createPostUpdatePluginWarning({
-        pluginId: outcome.pluginId,
-        reason: outcome.message,
-      }),
-    );
   }
 
   const remainingMissingPayloads = await collectMissingPluginInstallPayloads({
@@ -1297,7 +1255,7 @@ async function updatePluginsAfterCoreUpdate(params: {
 
   if (params.opts.json) {
     return {
-      status: "ok",
+      status: warnings.length > 0 ? "warning" : "ok",
       changed: pluginsChanged,
       warnings,
       sync: {
@@ -1367,7 +1325,7 @@ async function updatePluginsAfterCoreUpdate(params: {
   }
 
   return {
-    status: "ok",
+    status: warnings.length > 0 ? "warning" : "ok",
     changed: pluginsChanged,
     warnings,
     sync: {
@@ -1719,7 +1677,10 @@ async function readPostCorePluginUpdateResultFile(
     if (
       parsed &&
       typeof parsed === "object" &&
-      (parsed.status === "ok" || parsed.status === "skipped" || parsed.status === "error")
+      (parsed.status === "ok" ||
+        parsed.status === "warning" ||
+        parsed.status === "skipped" ||
+        parsed.status === "error")
     ) {
       return parsed;
     }
@@ -2338,13 +2299,29 @@ export async function updateCommand(opts: UpdateCommandOptions): Promise<void> {
   const resultWithPostUpdate: UpdateRunResult = postCorePluginUpdate
     ? {
         ...result,
+        status: postCorePluginUpdate.status === "error" ? "error" : result.status,
+        ...(postCorePluginUpdate.status === "error" ? { reason: "post-update-plugins" } : {}),
         postUpdate: {
           ...result.postUpdate,
           plugins: postCorePluginUpdate,
         },
       }
     : result;
 
+  if (postCorePluginUpdate?.status === "error") {
+    if (opts.json) {
+      defaultRuntime.writeJson(resultWithPostUpdate);
+    } else {
+      defaultRuntime.error(theme.error("Update failed during plugin post-update sync."));
+    }
+    await maybeRestartServiceAfterFailedPackageUpdate({
+      prePackageServiceStop,
+      jsonMode: Boolean(opts.json),
+    });
+    defaultRuntime.exit(1);
+    return;
+  }
+
   let restartScriptPath: string | null = null;
   let refreshGatewayServiceEnv = false;
   let gatewayServiceEnv: NodeJS.ProcessEnv | undefined;
diff --git a/src/infra/update-runner.ts b/src/infra/update-runner.ts
@@ -58,7 +58,7 @@ export type UpdateRunResult = {
   durationMs: number;
   postUpdate?: {
     plugins?: {
-      status: "ok" | "skipped" | "error";
+      status: "ok" | "warning" | "skipped" | "error";
       reason?: string;
       changed: boolean;
       warnings?: Array<{

Original file line number	Diff line number	Diff line change
`@@ -121,16 +121,20 @@ function assertCorruptUpdate(updateJsonPath, pluginId) {`
`121`	`121`	`if (!plugins) {`
`122`	`122`	throw new Error(`missing postUpdate.plugins in update output: ${JSON.stringify(payload)}`);
`123`	`123`	`}`
`124`		`- if (plugins.status !== "ok") {`
`125`		- throw new Error(`expected post-update plugin status ok, got ${JSON.stringify(plugins.status)}`);
	`124`	`+ if (plugins.status !== "warning") {`
	`125`	`+ throw new Error(`
	`126`	+ `expected post-update plugin status warning, got ${JSON.stringify(plugins.status)}`,
	`127`	`+ );`
`126`	`128`	`}`
`127`	`129`	`assertCorruptPluginDetails(plugins, pluginId);`
`128`	`130`	`}`
`129`	`131`
`130`	`132`	`function assertCorruptPluginResult(pluginJsonPath, pluginId) {`
`131`	`133`	`const plugins = readJson(pluginJsonPath);`
`132`		`- if (plugins.status !== "ok") {`
`133`		- throw new Error(`expected post-update plugin status ok, got ${JSON.stringify(plugins.status)}`);
	`134`	`+ if (plugins.status !== "warning") {`
	`135`	`+ throw new Error(`
	`136`	+ `expected post-update plugin status warning, got ${JSON.stringify(plugins.status)}`,
	`137`	`+ );`
`134`	`138`	`}`
`135`	`139`	`assertCorruptPluginDetails(plugins, pluginId);`
`136`	`140`	`}`