fix(plugins): keep derived metadata snapshots fresh

vincentkoc · vincentkoc · commit 36bca54a61a9 · 2026-05-22T11:00:56.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -959,7 +959,7 @@ Docs: https://docs.openclaw.ai
 - CLI/plugins: route lazy plugin command-registration chatter to stderr only during JSON-output command registration, keeping plugin-backed `--json` stdout parseable without changing parse-only or pass-through `--json` behavior. Fixes #81535. (#81536) Thanks @ScientificProgrammer and @vincentkoc.
 - Plugins: treat git plugin install refs as refs instead of checkout flags, so option-like selectors fail checkout instead of silently installing the default branch. Fixes #79898. (#79901) Thanks @afurm and @vincentkoc.
 - Doctor/memory: stop warning that no memory plugin is active when an enabled alternate memory plugin explicitly owns the memory slot, while preserving the warning for missing or disabled slot entries. Fixes #78540. (#78557) Thanks @carladams1299-lab and @vincentkoc.
-- Plugins: keep process-local plugin metadata snapshot memo freshness tied to the cached registry snapshot so policy-stale derived plugin metadata edits invalidate the memo instead of returning stale owners or command aliases. (#81064) Thanks @Kaspre.
+- Plugins: keep derived plugin metadata snapshots uncached when the persisted registry is missing, disabled, or stale, so newly added plugins are discovered without restarting. (#81064) Thanks @Kaspre.
 - Plugins: discover provider plugins from `setup.providers[].envVars` credentials during provider discovery while keeping the deprecated `providerAuthEnvVars` fallback. (#81542) Thanks @JARVIS-Glasses.
 - Docs/Codex harness: clarify that per-agent `CODEX_HOME` isolates `~/.codex` while inherited `HOME` intentionally keeps `.agents` discovery and subprocess user-home state available.
 - CLI/plugins: keep bare plugin and parent-command help on the lightweight path, avoiding plugin registry discovery before rendering help.
diff --git a/src/plugins/current-plugin-metadata-snapshot.test.ts b/src/plugins/current-plugin-metadata-snapshot.test.ts
@@ -16,11 +16,13 @@ import type { PluginMetadataSnapshot } from "./plugin-metadata-snapshot.js";
 function createSnapshot(
   params: {
     config?: Parameters<typeof resolveInstalledPluginIndexPolicyHash>[0];
+    registrySource?: PluginMetadataSnapshot["registrySource"];
     workspaceDir?: string;
   } = {},
 ): PluginMetadataSnapshot {
   return {
     policyHash: resolveInstalledPluginIndexPolicyHash(params.config),
+    ...(params.registrySource ? { registrySource: params.registrySource } : {}),
     ...(params.workspaceDir ? { workspaceDir: params.workspaceDir } : {}),
     index: {
       version: 1,
@@ -216,6 +218,14 @@ describe("current plugin metadata snapshot", () => {
     expect(getCurrentPluginMetadataSnapshot()).toBeUndefined();
   });
 
+  it("does not keep derived registry snapshots as the current snapshot", () => {
+    const persisted = createSnapshot({ registrySource: "persisted" });
+    setCurrentPluginMetadataSnapshot(persisted);
+    setCurrentPluginMetadataSnapshot(createSnapshot({ registrySource: "derived" }));
+
+    expect(getCurrentPluginMetadataSnapshot()).toBeUndefined();
+  });
+
   it("restores a captured current snapshot state", () => {
     const firstConfig = { plugins: { allow: ["first"] } };
     const secondConfig = { plugins: { allow: ["second"] } };
diff --git a/src/plugins/current-plugin-metadata-snapshot.ts b/src/plugins/current-plugin-metadata-snapshot.ts
@@ -23,6 +23,12 @@ export function resolvePluginMetadataControlPlaneFingerprint(
   });
 }
 
+export function isReusableCurrentPluginMetadataSnapshot(
+  snapshot: PluginMetadataSnapshot,
+): boolean {
+  return snapshot.registrySource !== "derived";
+}
+
 // Single-slot Gateway-owned handoff. Replace or clear it at lifecycle boundaries;
 // never accumulate historical metadata snapshots here.
 export function setCurrentPluginMetadataSnapshot(
@@ -34,6 +40,10 @@ export function setCurrentPluginMetadataSnapshot(
     workspaceDir?: string;
   } = {},
 ): void {
+  if (snapshot && !isReusableCurrentPluginMetadataSnapshot(snapshot)) {
+    clearCurrentPluginMetadataSnapshotState();
+    return;
+  }
   const compatiblePolicyHashes = snapshot
     ? options.compatibleConfigs?.map((config) => resolveInstalledPluginIndexPolicyHash(config))
     : undefined;
diff --git a/src/plugins/plugin-metadata-snapshot.memo.test.ts b/src/plugins/plugin-metadata-snapshot.memo.test.ts
@@ -254,7 +254,7 @@ describe("loadPluginMetadataSnapshot process memo", () => {
     expect(second.byPluginId.get("demo")).toBe(second.plugins[0]);
   });
 
-  it("memoizes policy-stale derived snapshots used by validation callers", () => {
+  it("does not memoize policy-stale derived snapshots", () => {
     const stateDir = tempStateDir();
     touchPersistedIndex(stateDir);
     loadPluginRegistrySnapshotWithMetadata.mockReturnValue({
@@ -272,7 +272,7 @@ describe("loadPluginMetadataSnapshot process memo", () => {
     loadPluginMetadataSnapshot({ config: {}, env: {}, stateDir });
     loadPluginMetadataSnapshot({ config: {}, env: {}, stateDir });
 
-    expect(loadPluginRegistrySnapshotWithMetadata).toHaveBeenCalledOnce();
+    expect(loadPluginRegistrySnapshotWithMetadata).toHaveBeenCalledTimes(2);
   });
 
   it("refreshes policy-stale derived snapshots when derived plugin files change", () => {
diff --git a/src/plugins/plugin-metadata-snapshot.ts b/src/plugins/plugin-metadata-snapshot.ts
@@ -768,18 +768,7 @@ function canMemoizePluginMetadataSnapshotResult(result: {
   registrySource: PluginRegistrySnapshotSource;
   snapshot: PluginMetadataSnapshot;
 }): boolean {
-  if (result.snapshot.index.plugins.length === 0) {
-    return false;
-  }
-  if (result.registrySource !== "derived") {
-    return true;
-  }
-  return (
-    result.snapshot.registryDiagnostics.length > 0 &&
-    result.snapshot.registryDiagnostics.every(
-      (diagnostic) => diagnostic.code === "persisted-registry-stale-policy",
-    )
-  );
+  return result.registrySource !== "derived" && result.snapshot.index.plugins.length > 0;
 }
 
 function loadPluginMetadataSnapshotImpl(params: LoadPluginMetadataSnapshotParams): {
@@ -831,6 +820,7 @@ function loadPluginMetadataSnapshotImpl(params: LoadPluginMetadataSnapshotParams
     registrySource: registryResult.source,
     snapshot: {
       policyHash: index.policyHash,
+      registrySource: registryResult.source,
       configFingerprint: resolvePluginMetadataControlPlaneFingerprint({
         config: params.config,
         env: params.env,
diff --git a/src/plugins/plugin-metadata-snapshot.types.ts b/src/plugins/plugin-metadata-snapshot.types.ts
@@ -2,6 +2,7 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { InstalledPluginIndex } from "./installed-plugin-index.js";
 import type { PluginManifestRecord, PluginManifestRegistry } from "./manifest-registry.js";
 import type { PluginDiagnostic } from "./manifest-types.js";
+import type { PluginRegistrySnapshotSource } from "./plugin-registry-snapshot.js";
 
 export type PluginMetadataSnapshotOwnerMaps = {
   channels: ReadonlyMap<string, readonly string[]>;
@@ -36,6 +37,7 @@ export type PluginMetadataSnapshotRegistryDiagnostic = {
 export type PluginMetadataSnapshot = {
   policyHash: string;
   configFingerprint?: string;
+  registrySource?: PluginRegistrySnapshotSource;
   workspaceDir?: string;
   index: InstalledPluginIndex;
   registryDiagnostics: readonly PluginMetadataSnapshotRegistryDiagnostic[];
diff --git a/src/plugins/runtime/load-context.test.ts b/src/plugins/runtime/load-context.test.ts
@@ -22,6 +22,7 @@ const metadataSnapshot = {
 const loadPluginMetadataSnapshotMock = vi.fn(() => metadataSnapshot);
 const getCurrentPluginMetadataSnapshotMock = vi.fn(() => undefined);
 const setCurrentPluginMetadataSnapshotMock = vi.fn();
+const clearCurrentPluginMetadataSnapshotMock = vi.fn();
 
 let resolvePluginRuntimeLoadContext: typeof import("./load-context.js").resolvePluginRuntimeLoadContext;
 let buildPluginRuntimeLoadOptions: typeof import("./load-context.js").buildPluginRuntimeLoadOptions;
@@ -47,7 +48,11 @@ vi.mock("../plugin-metadata-snapshot.js", () => ({
 }));
 
 vi.mock("../current-plugin-metadata-snapshot.js", () => ({
+  clearCurrentPluginMetadataSnapshot: clearCurrentPluginMetadataSnapshotMock,
   getCurrentPluginMetadataSnapshot: getCurrentPluginMetadataSnapshotMock,
+  isReusableCurrentPluginMetadataSnapshot: (
+    snapshot: typeof metadataSnapshot & { registrySource?: "derived" },
+  ) => snapshot.registrySource !== "derived",
   setCurrentPluginMetadataSnapshot: setCurrentPluginMetadataSnapshotMock,
 }));
 
@@ -65,6 +70,7 @@ describe("resolvePluginRuntimeLoadContext", () => {
     loadPluginMetadataSnapshotMock.mockClear();
     getCurrentPluginMetadataSnapshotMock.mockClear();
     setCurrentPluginMetadataSnapshotMock.mockClear();
+    clearCurrentPluginMetadataSnapshotMock.mockClear();
     resolveAgentWorkspaceDirMock.mockClear();
     resolveDefaultAgentIdMock.mockClear();
 
@@ -134,6 +140,22 @@ describe("resolvePluginRuntimeLoadContext", () => {
     expect(resolveAgentWorkspaceDirMock).toHaveBeenCalledWith(resolvedConfig, "default");
   });
 
+  it("does not store derived metadata as the reusable runtime snapshot", () => {
+    const derivedSnapshot = { ...metadataSnapshot } as typeof metadataSnapshot & {
+      registrySource: "derived";
+    };
+    derivedSnapshot.registrySource = "derived";
+    loadPluginMetadataSnapshotMock.mockReturnValueOnce(derivedSnapshot);
+
+    resolvePluginRuntimeLoadContext({
+      config: { plugins: {} },
+      env: { HOME: "/tmp/openclaw-home" } as NodeJS.ProcessEnv,
+    });
+
+    expect(setCurrentPluginMetadataSnapshotMock).not.toHaveBeenCalled();
+    expect(clearCurrentPluginMetadataSnapshotMock).toHaveBeenCalledOnce();
+  });
+
   it("uses the source runtime snapshot for plugin activation source config", () => {
     const runtimeConfig = { plugins: {} };
     const sourceConfig = {
diff --git a/src/plugins/runtime/load-context.ts b/src/plugins/runtime/load-context.ts
@@ -6,7 +6,9 @@ import type { PluginInstallRecord } from "../../config/types.plugins.js";
 import { createSubsystemLogger } from "../../logging.js";
 import { resolvePluginActivationSourceConfig } from "../activation-source-config.js";
 import {
+  clearCurrentPluginMetadataSnapshot,
   getCurrentPluginMetadataSnapshot,
+  isReusableCurrentPluginMetadataSnapshot,
   setCurrentPluginMetadataSnapshot,
 } from "../current-plugin-metadata-snapshot.js";
 import { extractPluginInstallRecordsFromInstalledPluginIndex } from "../installed-plugin-index-install-records.js";
@@ -95,12 +97,16 @@ export function resolvePluginRuntimeLoadContext(
   const workspaceDir =
     options?.workspaceDir ?? resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
   if (metadataSnapshot) {
-    setCurrentPluginMetadataSnapshot(metadataSnapshot, {
-      config: rawConfig,
-      compatibleConfigs: [config, activationSourceConfig],
-      env,
-      workspaceDir,
-    });
+    if (isReusableCurrentPluginMetadataSnapshot(metadataSnapshot)) {
+      setCurrentPluginMetadataSnapshot(metadataSnapshot, {
+        config: rawConfig,
+        compatibleConfigs: [config, activationSourceConfig],
+        env,
+        workspaceDir,
+      });
+    } else {
+      clearCurrentPluginMetadataSnapshot();
+    }
   }
   return {
     rawConfig,
