Summary

• Tool-discovery plugin loads run with activate: false and a tool-only plugin scope, so the registry they build omits provider-only plugins.
• installStandaloneRegistry unconditionally called setActivePluginRegistry, so those loads replaced the live active registry and wiped its providers. The gateway tools-catalog channel load behind agents.list (and the resolvePluginTools cold-load) hit this path, so a bundled provider plugin disappeared at runtime after the first tool-discovery load.
• Fix: a tool-discovery load becomes the active registry only when none exists yet (cold start). Once an active registry is present, the tool-only registry is only pinned to its requested channel/http-route surface, so the live providers are preserved. The cold-start promotion still initializes runtime state (cache key / workspaceDir), so later surface lookups hit and the bootstrap path does not reload redundantly.
• Also source plugin tool catalog metadata and declared tools from the active registry, the selected channel registry, and the raw pinned channel registry, so a tool-only plugin's display name, description, risk, and tags survive even when the channel selector returns an active registry that has channels. The active registry stays authoritative for duplicate keys.
• Out of scope: normal activation (activate !== false) and the migration provider runtime, which intentionally relies on setActivePluginRegistry and does not set toolDiscovery.
• Reviewers should focus on installStandaloneRegistry (cold-start promotion vs pin-only) and the tools.catalog metadata merge (active + selected channel + raw pinned channel).

Linked context

No linked issue; this is a standalone runtime bug fix. Not requested by a maintainer.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: After the first tool-discovery load (e.g. a gateway agents.list / tools-catalog call), getActivePluginRegistry().providers dropped to an empty array, so a bundled provider-only plugin vanished from the live runtime even though it was loaded at startup.
• Real environment tested: OpenClaw gateway running from a packaged build on Windows, where the defect was first observed through console instrumentation in setActivePluginRegistry (active providers going from 1 to 0 on the tool-discovery stack). Verified after the patch with a Node reproduction (tsx) driving the real loader/runtime source on this branch (Node 22, this checkout).
• Exact steps or command run after this patch: npx tsx __repro_provider_clobber.mts it seeds an active registry that carries a provider-only plugin, then drives the real ensureStandaloneRuntimePluginRegistryLoaded channel tool-discovery path that the gateway tools-catalog / agents.list relies on, and prints the active providers count before and after.
• Evidence after fix (terminal capture): copied live terminal output after the patch:

REPRO providers BEFORE tool-discovery : 1
REPRO providers AFTER  tool-discovery : 1
REPRO active registry was replaced?   : false
REPRO RESULT                          : PROVIDERS PRESERVED

• Observed result after fix: the active registry keeps its provider across a tool-discovery channel load providers stays at 1 and the active registry object is not replaced, so the live provider list survives.
• What was not tested: a full over-the-wire agents.list round-trip inside the packaged gateway binary was not re-run after a full rebuild; provider preservation was confirmed through the Node reproduction and the loader regression coverage instead.
• Proof limitations or environment constraints: the reproduction drives the real loader/runtime source through tsx rather than the fully repackaged gateway binary, because rebuilding and re-syncing the packaged runtime into the host application is out of band for this checkout. The pre-fix symptom itself was captured in the live gateway runtime via console instrumentation.
• Before evidence (optional but encouraged): same script with the patch stashed (guard removed):

REPRO providers BEFORE tool-discovery : 1
REPRO providers AFTER  tool-discovery : 0
REPRO active registry was replaced?   : true
REPRO RESULT                          : PROVIDERS CLEARED

import { createEmptyPluginRegistry } from "./src/plugins/registry-empty.js";
import {
  getActivePluginRegistry,
  resetPluginRuntimeStateForTest,
  setActivePluginRegistry,
} from "./src/plugins/runtime.js";
import { ensureStandaloneRuntimePluginRegistryLoaded } from "./src/plugins/runtime/standalone-runtime-registry-loader.js";

resetPluginRuntimeStateForTest();

const active = createEmptyPluginRegistry();
active.plugins.push({ id: "qclaw", status: "loaded" } as never);
active.providers.push({ id: "qclaw", pluginId: "qclaw" } as never);
setActivePluginRegistry(active, "startup-key", "default", "/tmp/ws");

console.log("REPRO providers BEFORE tool-discovery :", getActivePluginRegistry()?.providers.length);

ensureStandaloneRuntimePluginRegistryLoaded({
  surface: "channel",
  forceLoad: true,
  loadOptions: {
    config: { plugins: { enabled: true } } as never,
    onlyPluginIds: ["__repro_tool_plugin__"],
    activate: false,
    toolDiscovery: true,
    workspaceDir: "/tmp/ws",
  },
});

const after = getActivePluginRegistry();
console.log("REPRO providers AFTER  tool-discovery :", after?.providers.length);
console.log("REPRO active registry was replaced?   :", after !== active);
console.log(
  "REPRO RESULT                          :",
  after?.providers.length ? "PROVIDERS PRESERVED" : "PROVIDERS CLEARED",
);

Tests and validation

• Focused suites (all green): node scripts/run-vitest.mjs src/plugins/runtime/standalone-runtime-registry-loader.test.ts src/gateway/server-methods/tools-catalog.test.ts src/plugins/tools.optional.test.ts -> gateway shard 16/16, plugins shard 73/73.
• Types: pnpm tsgo:core and pnpm tsgo:test:src are clean for the changed files; git diff --check is clean.
• Ran the Node reproduction above before and after the patch (see Real behavior proof).
• Regression coverage:
  • loader (standalone-runtime-registry-loader.test.ts): a toolDiscovery channel load pins the channel surface without replacing an existing active registry; a toolDiscovery active load does not replace an existing active registry; a toolDiscovery load initializes the active registry when none exists (cold start); a non-toolDiscovery active load still installs as the active registry (migration provider path).
  • catalog (tools-catalog.test.ts): plugin tool metadata is projected from the pinned channel registry; and from the raw pinned channel registry even when the channel selector returns an active registry that has channels (the active-with-channels + pinned-tool-only case).
• What failed before this fix: the reproduction showed the active providers dropping from 1 to 0 (active registry replaced) before the guard was added.

Risk checklist

• Did user-visible behavior change? Yes once an active registry exists, provider-only plugins are no longer wiped from it by tool-discovery loads.
• Did config, environment, or migration behavior change? No the migration provider runtime load has no toolDiscovery flag and still installs as the active registry exactly as before.
• Did security, auth, secrets, network, or tool execution behavior change? No.
• Highest-risk area: changing when a standalone load becomes globally active (cold-start promotion vs pin-only) and the tools.catalog metadata source.
• How is that risk mitigated: full activation (activate !== false) and the migration-provider path are unchanged; on a true cold start the promoted tool-only registry is replaced by the first full activation; catalog metadata reads the raw pinned channel registry so tool-only plugins are not hidden by the channel selector; the loader and tools.catalog branches are covered by regression tests.

Current review state

• Next action: maintainer review (the open ClawSweeper P1 below is addressed).
• Copilot review: addressed the load cache that prevents reloads (setCachedPluginRegistry / getReusableCachedPluginRegistry) is keyed off the load cache key and is independent of setActivePluginRegistry, so skipping the active-registry write does not cause extra plugin reloads.
• ClawSweeper P1 (raw pinned registry): addressed tools.catalog now merges metadata and declared tools from the raw pinned channel registry (getPinnedActivePluginChannelRegistry) in addition to the active and selected channel registries, so a pinned tool-only registry is read even when getActivePluginChannelRegistry() selects an active registry that has channels. Added a regression for the active-with-channels + pinned-tool-only case.