Summary

• route channels add through the same trust-aware catalog discovery used by setup flows
• block disabled workspace channel plugins from entering setup-only loader and registry paths, even when explicitly scoped
• fix loader setup-only gate to allow trusted workspace plugins (was over-blocking all workspace origins)
• mark the unfiltered listChannelPluginCatalogEntries as @deprecated and migrate internal callers to listChannelPluginCatalogEntriesUnfiltered (@internal)
• add regression coverage for both trusted-catalog resolution and untrusted workspace setup-only loads

Why

The original fix aligned channels add with the setup/catalog trust rules so the CLI no longer selected an untrusted workspace shadow when resolving a built-in channel id.

That still left a lower-level bypass: setup-only scoped loads could construct a temporary plugin registry and execute plugin code without going through the catalog trust filter first. In practice that meant an untrusted workspace channel plugin could still be imported and registered during setup-time flows if it reached the loader directly.

The hardening here keeps the catalog fix, but moves the security boundary down to the shared setup-time loader/registry entry so downstream callers do not need to each remember to re-apply the same trust rule.

graph TD
    SOURCES["Plugin source directories"] --> MANIFEST["Manifest Registry<br/>(pluginId + origin + channels)"]

    MANIFEST -->|"setup/add"| TRUSTED["listTrustedChannelPluginCatalogEntries<br/>✅ strict: untrusted workspace-only dropped"]
    MANIFEST -->|"setup/add"| DISCOVERY["listSetupDiscoveryChannelPluginCatalogEntries<br/>⚠️ lenient: untrusted workspace-only kept"]
    MANIFEST -->|"gateway"| GW["Gateway startup selection<br/>no catalog trust filter"]

    TRUSTED --> ONBOARD["onboard / setup"]
    TRUSTED --> ADD["channels add<br/>✅ now uses strict list"]
    DISCOVERY --> SETUP_UI["setup wizard installable list<br/>(UI discovery only)"]
    ONBOARD --> LOAD
    ADD --> LOAD
    GW --> LOAD

    LOAD["loadOpenClawPlugins()<br/>imports plugin module<br/>executes register(...)<br/><br/>trust enforcement now lives here<br/>✅ gate based on enableState<br/>(trusted workspace → allowed)"]
    LOAD --> SNAP["Snapshot Registry<br/>(temporary setup/add registry)"]
    LOAD --> ACTIVE["Active Runtime Registry<br/>(gateway global registry)"]
    SNAP --> SNAPUSE["validateInput()<br/>applyAccountConfig()<br/>write config<br/>setup/lifecycle callbacks"]

    style TRUSTED fill:#d4edda,stroke:#28a745
    style ADD fill:#d4edda,stroke:#28a745
    style DISCOVERY fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style SETUP_UI fill:#eeeeee,stroke:#999999
    style LOAD fill:#d4edda,stroke:#28a745,stroke-width:3px
    style SNAP fill:#d9edf7,stroke:#31708f
    style SNAPUSE fill:#eeeeee,stroke:#999999
    style ACTIVE fill:#d4edda,stroke:#28a745

The key point is that both the gateway path and the setup/add snapshot path pass through loadOpenClawPlugins() before they can construct runtime-visible registry content. Blocking untrusted workspace channel shadows there keeps them out of both:

• the active runtime registry used by gateway/runtime lookups
• the temporary snapshot registry used by setup/add flows

onboard, setup, and now channels add all use the strict trusted catalog list (which drops untrusted workspace-only entries). The lenient discovery list is only used for the setup wizard's "installable" display bucket. The loader/registry enforcement is the lower-level backstop that prevents setup-time code execution even if a caller somehow bypasses the catalog layer.

Catalog API hardening

listChannelPluginCatalogEntries (the unfiltered raw listing) is not part of the plugin SDK — it is not exported through any plugin-sdk entrypoint and third-party plugins cannot import it. To prevent internal misuse:

• listChannelPluginCatalogEntries is now @deprecated — IDE shows strikethrough, guiding developers to the safe alternatives
• listChannelPluginCatalogEntriesUnfiltered (@internal) — extracted for use by trusted-catalog.ts internals without triggering deprecation warnings
• listTrustedChannelPluginCatalogEntries — the recommended entry point for all execution-facing paths
• listSetupDiscoveryChannelPluginCatalogEntries — documented as UI-only, with explicit warning against execution use

Tests

• pnpm test src/plugins/loader.test.ts -t "does not setup-load untrusted workspace channel plugins even when explicitly scoped"
• pnpm test src/commands/channel-setup/channel-plugin-resolution.test.ts
• pnpm test src/commands/channel-setup/trusted-catalog.test.ts

Notes

• pnpm tsgo in this worktree still hits unrelated existing failures outside the touched surface.