fix(plugins): enforce synchronous registration

src/plugins/cli-registry-loader.ts

@@ -47,28 +47,6 @@ function resolvePluginCliLogger(logger?: PluginLogger): PluginLogger {
   return logger ?? createPluginCliLogger();
 }
 
-function hasIgnoredAsyncPluginRegistration(registry: PluginRegistry): boolean {
-  return (registry.diagnostics ?? []).some(
-    (entry) =>
-      entry.message === "plugin register returned a promise; async registration is ignored",
-  );
-}
-
-function mergeCliRegistrars(params: {
-  runtimeRegistry: PluginRegistry;
-  metadataRegistry: PluginRegistry;
-}): PluginRegistry["cliRegistrars"] {
-  const runtimeCommands = new Set(
-    params.runtimeRegistry.cliRegistrars.flatMap((entry) => entry.commands),
-  );
-  return [
-    ...params.runtimeRegistry.cliRegistrars,
-    ...params.metadataRegistry.cliRegistrars.filter(
-      (entry) => !entry.commands.some((command) => runtimeCommands.has(command)),
-    ),
-  ];
-}
-
 function buildPluginCliLoaderParams(
   context: PluginCliLoadContext,
   params?: { primaryCommand?: string },
@@ -129,48 +107,17 @@ export async function loadPluginCliCommandRegistryWithContext(params: {
   context: PluginCliLoadContext;
   primaryCommand?: string;
   loaderOptions?: PluginCliLoaderOptions;
-  onMetadataFallbackError: (error: unknown) => void;
 }): Promise<PluginCliRegistryLoadResult> {
-  const runtimeRegistry = loadOpenClawPlugins(
-    buildPluginCliLoaderParams(
-      params.context,
-      { primaryCommand: params.primaryCommand },
-      params.loaderOptions,
-    ),
-  );
-
-  if (!hasIgnoredAsyncPluginRegistration(runtimeRegistry)) {
-    return {
-      ...params.context,
-      registry: runtimeRegistry,
-    };
-  }
-
-  try {
-    const metadataRegistry = await loadOpenClawPluginCliRegistry(
+  return {
+    ...params.context,
+    registry: loadOpenClawPlugins(
       buildPluginCliLoaderParams(
         params.context,
         { primaryCommand: params.primaryCommand },
         params.loaderOptions,
       ),
-    );
-    return {
-      ...params.context,
-      registry: {
-        ...runtimeRegistry,
-        cliRegistrars: mergeCliRegistrars({
-          runtimeRegistry,
-          metadataRegistry,
-        }),
-      },
-    };
-  } catch (error) {
-    params.onMetadataFallbackError(error);
-    return {
-      ...params.context,
-      registry: runtimeRegistry,
-    };
-  }
+    ),
+  };
 }
 
 function buildPluginCliCommandGroupEntries(params: {
@@ -194,10 +141,6 @@ function buildPluginCliCommandGroupEntries(params: {
   }));
 }
 
-function logPluginCliMetadataFallbackError(logger: PluginLogger, error: unknown) {
-  logger.warn(`plugin CLI metadata fallback failed: ${String(error)}`);
-}
-
 export async function loadPluginCliDescriptors(
   params: PluginCliPublicLoadParams,
 ): Promise<OpenClawPluginCliCommandDescriptor[]> {
@@ -227,7 +170,6 @@ export async function loadPluginCliRegistrationEntries(params: {
   loaderOptions?: PluginCliLoaderOptions;
   logger?: PluginLogger;
   primaryCommand?: string;
-  onMetadataFallbackError: (error: unknown) => void;
 }): Promise<PluginCliCommandGroupEntry[]> {
   const resolvedLogger = resolvePluginCliLogger(params.logger);
   const context = resolvePluginCliLoadContext({
@@ -239,7 +181,6 @@ export async function loadPluginCliRegistrationEntries(params: {
     context,
     primaryCommand: params.primaryCommand,
     loaderOptions: params.loaderOptions,
-    onMetadataFallbackError: params.onMetadataFallbackError,
   });
   return buildPluginCliCommandGroupEntries({
     registry,
@@ -256,8 +197,5 @@ export async function loadPluginCliRegistrationEntriesWithDefaults(
   return loadPluginCliRegistrationEntries({
     ...params,
     logger,
-    onMetadataFallbackError: (error) => {
-      logPluginCliMetadataFallbackError(logger, error);
-    },
   });
 }

src/plugins/cli.test.ts

@@ -81,13 +81,6 @@ function createCliRegistry(params?: {
   };
 }
 
-function createEmptyCliRegistry(params?: { diagnostics?: Array<{ message: string }> }) {
-  return {
-    cliRegistrars: [],
-    diagnostics: params?.diagnostics ?? [],
-  };
-}
-
 function createAutoEnabledCliFixture() {
   const rawConfig = {
     plugins: {},
@@ -310,51 +303,6 @@ describe("registerPluginCliCommands", () => {
     expect(mocks.loadOpenClawPluginCliRegistry).not.toHaveBeenCalled();
   });
 
-  it("falls back to awaited CLI metadata collection when runtime loading ignored async registration", async () => {
-    const asyncRegistrar = vi.fn(async ({ program }: { program: Command }) => {
-      const asyncCommand = program.command("async-cli").description("Async CLI");
-      asyncCommand.command("run").action(mocks.memoryListAction);
-    });
-    mocks.loadOpenClawPlugins.mockReturnValue(
-      createEmptyCliRegistry({
-        diagnostics: [
-          {
-            message: "plugin register returned a promise; async registration is ignored",
-          },
-        ],
-      }),
-    );
-    mocks.loadOpenClawPluginCliRegistry.mockResolvedValue({
-      cliRegistrars: [
-        {
-          pluginId: "async-plugin",
-          register: asyncRegistrar,
-          commands: ["async-cli"],
-          descriptors: [
-            {
-              name: "async-cli",
-              description: "Async CLI",
-              hasSubcommands: true,
-            },
-          ],
-          source: "bundled",
-        },
-      ],
-      diagnostics: [],
-    });
-    const program = createProgram();
-    program.exitOverride();
-
-    await registerPluginCliCommands(program, {} as OpenClawConfig, undefined, undefined, {
-      mode: "lazy",
-    });
-
-    expect(mocks.loadOpenClawPluginCliRegistry).toHaveBeenCalledTimes(1);
-    await program.parseAsync(["async-cli", "run"], { from: "user" });
-    expect(asyncRegistrar).toHaveBeenCalledTimes(1);
-    expect(mocks.memoryListAction).toHaveBeenCalledTimes(1);
-  });
-
   it("lazy-registers descriptor-backed plugin commands on first invocation", async () => {
     const program = createProgram();
     program.exitOverride();

src/plugins/loader.cli-metadata.test.ts

@@ -549,7 +549,7 @@ module.exports = {
     );
   });
 
-  it("awaits async plugin registration when collecting CLI metadata", async () => {
+  it("rejects async plugin registration when collecting CLI metadata", async () => {
     useNoBundledPlugins();
     const plugin = writePlugin({
       id: "async-cli",
@@ -580,10 +580,11 @@ module.exports = {
       },
     });
 
-    expect(registry.cliRegistrars.flatMap((entry) => entry.commands)).toContain("async-cli");
-    expect(
-      registry.diagnostics.some((entry) => entry.message.includes("async registration is ignored")),
-    ).toBe(false);
+    expect(registry.cliRegistrars.flatMap((entry) => entry.commands)).not.toContain("async-cli");
+    const loaded = registry.plugins.find((entry) => entry.id === "async-cli");
+    expect(loaded?.status).toBe("error");
+    expect(loaded?.failurePhase).toBe("register");
+    expect(loaded?.error).toContain("plugin register must be synchronous");
   });
 
   it("applies memory slot gating to non-bundled CLI metadata loads", async () => {

src/plugins/loader.test.ts

@@ -1159,6 +1159,39 @@ describe("loadOpenClawPlugins", () => {
         ).toBe(true);
       },
     },
+    {
+      label: "rejects async register functions instead of silently loading them",
+      run: () => {
+        useNoBundledPlugins();
+        const plugin = writePlugin({
+          id: "async-register",
+          filename: "async-register.cjs",
+          body: `module.exports = {
+  id: "async-register",
+  async register(api) {
+    await Promise.resolve();
+    api.registerGatewayMethod("async-register.ping", ({ respond }) => respond(true, { ok: true }));
+  },
+};`,
+        });
+
+        const registry = loadOpenClawPlugins({
+          cache: false,
+          config: {
+            plugins: {
+              load: { paths: [plugin.file] },
+              allow: ["async-register"],
+            },
+          },
+        });
+
+        const loaded = registry.plugins.find((entry) => entry.id === "async-register");
+        expect(loaded?.status).toBe("error");
+        expect(loaded?.failurePhase).toBe("register");
+        expect(loaded?.error).toContain("plugin register must be synchronous");
+        expect(Object.keys(registry.gatewayHandlers)).not.toContain("async-register.ping");
+      },
+    },
     {
       label: "limits imports to the requested plugin ids",
       run: () => {

src/plugins/loader.ts

@@ -98,7 +98,12 @@ import {
   shouldPreferNativeJiti,
 } from "./sdk-alias.js";
 import { hasKind, kindsEqual } from "./slots.js";
-import type { OpenClawPluginDefinition, OpenClawPluginModule, PluginLogger } from "./types.js";
+import type {
+  OpenClawPluginApi,
+  OpenClawPluginDefinition,
+  OpenClawPluginModule,
+  PluginLogger,
+} from "./types.js";
 
 export type PluginLoadResult = PluginRegistry;
 
@@ -250,6 +255,162 @@ function profilePluginLoaderSync<T>(params: {
   }
 }
 
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+type PluginRegistrySnapshot = {
+  arrays: {
+    tools: PluginRegistry["tools"];
+    hooks: PluginRegistry["hooks"];
+    typedHooks: PluginRegistry["typedHooks"];
+    channels: PluginRegistry["channels"];
+    channelSetups: PluginRegistry["channelSetups"];
+    providers: PluginRegistry["providers"];
+    cliBackends: NonNullable<PluginRegistry["cliBackends"]>;
+    textTransforms: PluginRegistry["textTransforms"];
+    speechProviders: PluginRegistry["speechProviders"];
+    realtimeTranscriptionProviders: PluginRegistry["realtimeTranscriptionProviders"];
+    realtimeVoiceProviders: PluginRegistry["realtimeVoiceProviders"];
+    mediaUnderstandingProviders: PluginRegistry["mediaUnderstandingProviders"];
+    imageGenerationProviders: PluginRegistry["imageGenerationProviders"];
+    videoGenerationProviders: PluginRegistry["videoGenerationProviders"];
+    musicGenerationProviders: PluginRegistry["musicGenerationProviders"];
+    webFetchProviders: PluginRegistry["webFetchProviders"];
+    webSearchProviders: PluginRegistry["webSearchProviders"];
+    memoryEmbeddingProviders: PluginRegistry["memoryEmbeddingProviders"];
+    agentHarnesses: PluginRegistry["agentHarnesses"];
+    httpRoutes: PluginRegistry["httpRoutes"];
+    cliRegistrars: PluginRegistry["cliRegistrars"];
+    reloads: NonNullable<PluginRegistry["reloads"]>;
+    nodeHostCommands: NonNullable<PluginRegistry["nodeHostCommands"]>;
+    securityAuditCollectors: NonNullable<PluginRegistry["securityAuditCollectors"]>;
+    services: PluginRegistry["services"];
+    commands: PluginRegistry["commands"];
+    conversationBindingResolvedHandlers: PluginRegistry["conversationBindingResolvedHandlers"];
+    diagnostics: PluginRegistry["diagnostics"];
+  };
+  gatewayHandlers: PluginRegistry["gatewayHandlers"];
+  gatewayMethodScopes: NonNullable<PluginRegistry["gatewayMethodScopes"]>;
+};
+
+function snapshotPluginRegistry(registry: PluginRegistry): PluginRegistrySnapshot {
+  return {
+    arrays: {
+      tools: [...registry.tools],
+      hooks: [...registry.hooks],
+      typedHooks: [...registry.typedHooks],
+      channels: [...registry.channels],
+      channelSetups: [...registry.channelSetups],
+      providers: [...registry.providers],
+      cliBackends: [...(registry.cliBackends ?? [])],
+      textTransforms: [...registry.textTransforms],
+      speechProviders: [...registry.speechProviders],
+      realtimeTranscriptionProviders: [...registry.realtimeTranscriptionProviders],
+      realtimeVoiceProviders: [...registry.realtimeVoiceProviders],
+      mediaUnderstandingProviders: [...registry.mediaUnderstandingProviders],
+      imageGenerationProviders: [...registry.imageGenerationProviders],
+      videoGenerationProviders: [...registry.videoGenerationProviders],
+      musicGenerationProviders: [...registry.musicGenerationProviders],
+      webFetchProviders: [...registry.webFetchProviders],
+      webSearchProviders: [...registry.webSearchProviders],
+      memoryEmbeddingProviders: [...registry.memoryEmbeddingProviders],
+      agentHarnesses: [...registry.agentHarnesses],
+      httpRoutes: [...registry.httpRoutes],
+      cliRegistrars: [...registry.cliRegistrars],
+      reloads: [...(registry.reloads ?? [])],
+      nodeHostCommands: [...(registry.nodeHostCommands ?? [])],
+      securityAuditCollectors: [...(registry.securityAuditCollectors ?? [])],
+      services: [...registry.services],
+      commands: [...registry.commands],
+      conversationBindingResolvedHandlers: [...registry.conversationBindingResolvedHandlers],
+      diagnostics: [...registry.diagnostics],
+    },
+    gatewayHandlers: { ...registry.gatewayHandlers },
+    gatewayMethodScopes: { ...registry.gatewayMethodScopes },
+  };
+}
+
+function restorePluginRegistry(registry: PluginRegistry, snapshot: PluginRegistrySnapshot): void {
+  registry.tools = snapshot.arrays.tools;
+  registry.hooks = snapshot.arrays.hooks;
+  registry.typedHooks = snapshot.arrays.typedHooks;
+  registry.channels = snapshot.arrays.channels;
+  registry.channelSetups = snapshot.arrays.channelSetups;
+  registry.providers = snapshot.arrays.providers;
+  registry.cliBackends = snapshot.arrays.cliBackends;
+  registry.textTransforms = snapshot.arrays.textTransforms;
+  registry.speechProviders = snapshot.arrays.speechProviders;
+  registry.realtimeTranscriptionProviders = snapshot.arrays.realtimeTranscriptionProviders;
+  registry.realtimeVoiceProviders = snapshot.arrays.realtimeVoiceProviders;
+  registry.mediaUnderstandingProviders = snapshot.arrays.mediaUnderstandingProviders;
+  registry.imageGenerationProviders = snapshot.arrays.imageGenerationProviders;
+  registry.videoGenerationProviders = snapshot.arrays.videoGenerationProviders;
+  registry.musicGenerationProviders = snapshot.arrays.musicGenerationProviders;
+  registry.webFetchProviders = snapshot.arrays.webFetchProviders;
+  registry.webSearchProviders = snapshot.arrays.webSearchProviders;
+  registry.memoryEmbeddingProviders = snapshot.arrays.memoryEmbeddingProviders;
+  registry.agentHarnesses = snapshot.arrays.agentHarnesses;
+  registry.httpRoutes = snapshot.arrays.httpRoutes;
+  registry.cliRegistrars = snapshot.arrays.cliRegistrars;
+  registry.reloads = snapshot.arrays.reloads;
+  registry.nodeHostCommands = snapshot.arrays.nodeHostCommands;
+  registry.securityAuditCollectors = snapshot.arrays.securityAuditCollectors;
+  registry.services = snapshot.arrays.services;
+  registry.commands = snapshot.arrays.commands;
+  registry.conversationBindingResolvedHandlers =
+    snapshot.arrays.conversationBindingResolvedHandlers;
+  registry.diagnostics = snapshot.arrays.diagnostics;
+  registry.gatewayHandlers = snapshot.gatewayHandlers;
+  registry.gatewayMethodScopes = snapshot.gatewayMethodScopes;
+}
+
+function createGuardedPluginRegistrationApi(api: OpenClawPluginApi): {
+  api: OpenClawPluginApi;
+  close: () => void;
+} {
+  let closed = false;
+  return {
+    api: new Proxy(api, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value !== "function") {
+          return value;
+        }
+        return (...args: unknown[]) => {
+          if (closed) {
+            return undefined;
+          }
+          return Reflect.apply(value, target, args);
+        };
+      },
+    }),
+    close: () => {
+      closed = true;
+    },
+  };
+}
+
+function runPluginRegisterSync(
+  register: NonNullable<OpenClawPluginDefinition["register"]>,
+  api: Parameters<NonNullable<OpenClawPluginDefinition["register"]>>[0],
+): void {
+  const guarded = createGuardedPluginRegistrationApi(api);
+  try {
+    const result = register(guarded.api);
+    if (isPromiseLike(result)) {
+      void Promise.resolve(result).catch(() => {});
+      throw new Error("plugin register must be synchronous");
+    }
+  } finally {
+    guarded.close();
+  }
+}
+
 /**
  * On Windows, the Node.js ESM loader requires absolute paths to be expressed
  * as file:// URLs (e.g. file:///C:/Users/...). Raw drive-letter paths like
@@ -2055,17 +2216,10 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi
       const previousMemoryCorpusSupplements = listMemoryCorpusSupplements();
       const previousMemoryPromptSupplements = listMemoryPromptSupplements();
       const previousMemoryRuntime = getMemoryRuntime();
+      const registrySnapshot = snapshotPluginRegistry(registry);
 
       try {
-        const result = register(api);
-        if (result && typeof result.then === "function") {
-          registry.diagnostics.push({
-            level: "warn",
-            pluginId: record.id,
-            source: record.source,
-            message: "plugin register returned a promise; async registration is ignored",
-          });
-        }
+        runPluginRegisterSync(register, api);
         // Snapshot loads should not replace process-global runtime prompt state.
         if (!shouldActivate) {
           restoreRegisteredAgentHarnesses(previousAgentHarnesses);
@@ -2082,6 +2236,7 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi
         registry.plugins.push(record);
         seenIds.set(pluginId, candidate.origin);
       } catch (err) {
+        restorePluginRegistry(registry, registrySnapshot);
         restoreRegisteredAgentHarnesses(previousAgentHarnesses);
         restoreRegisteredCompactionProviders(previousCompactionProviders);
         restoreRegisteredMemoryEmbeddingProviders(previousMemoryEmbeddingProviders);
@@ -2477,11 +2632,13 @@ export async function loadOpenClawPluginCliRegistry(
       },
     });
 
+    const registrySnapshot = snapshotPluginRegistry(registry);
     try {
-      await register(api);
+      runPluginRegisterSync(register, api);
       registry.plugins.push(record);
       seenIds.set(pluginId, candidate.origin);
     } catch (err) {
+      restorePluginRegistry(registry, registrySnapshot);
       recordPluginError({
         logger,
         registry,

src/plugins/types.ts

@@ -1838,13 +1838,11 @@ export type OpenClawPluginDefinition = {
   reload?: OpenClawPluginReloadRegistration;
   nodeHostCommands?: OpenClawPluginNodeHostCommand[];
   securityAuditCollectors?: OpenClawPluginSecurityAuditCollector[];
-  register?: (api: OpenClawPluginApi) => void | Promise<void>;
-  activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+  register?: (api: OpenClawPluginApi) => void;
+  activate?: (api: OpenClawPluginApi) => void;
 };
 
-export type OpenClawPluginModule =
-  | OpenClawPluginDefinition
-  | ((api: OpenClawPluginApi) => void | Promise<void>);
+export type OpenClawPluginModule = OpenClawPluginDefinition | ((api: OpenClawPluginApi) => void);
 
 export type PluginRegistrationMode = "full" | "setup-only" | "setup-runtime" | "cli-metadata";
 

src/test-utils/plugin-registration.ts

@@ -4,14 +4,14 @@ import type { OpenClawPluginApi, ProviderPlugin } from "../plugins/types.js";
 export { createCapturedPluginRegistration };
 
 type RegistrablePlugin = {
-  register(api: OpenClawPluginApi): void | Promise<void>;
+  register(api: OpenClawPluginApi): void;
 };
 
 export async function registerSingleProviderPlugin(params: {
-  register(api: OpenClawPluginApi): void | Promise<void>;
+  register(api: OpenClawPluginApi): void;
 }): Promise<ProviderPlugin> {
   const captured = createCapturedPluginRegistration();
-  await params.register(captured.api);
+  params.register(captured.api);
   const provider = captured.providers[0];
   if (!provider) {
     throw new Error("provider registration missing");
@@ -24,7 +24,7 @@ export async function registerProviderPlugins(
 ): Promise<ProviderPlugin[]> {
   const captured = createCapturedPluginRegistration();
   for (const plugin of plugins) {
-    await plugin.register(captured.api);
+    plugin.register(captured.api);
   }
   return captured.providers;
 }