Summary

• Problem: packaged plugin lazy loading can still enter the package-level runtime-deps planning path even when the requested plugin deps are already materialized.
• Why it matters: that path scans bundled plugin manifests and contributes avoidable filesystem work in the gateway CPU/event-loop starvation cluster.
• What changed: add a fast path that proves the requested plugin deps plus mirrored root deps are already materialized before scanning all bundled plugin manifests.
• What did NOT change (scope boundary): no install-root selection changes, no package-manager behavior changes, no Telegram/channel behavior changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related Gateway CPU spin causes Telegram replies to stall and status probe to time out #72338
• Related Plugin loader hot loop: prepareBundledPluginRuntimeDistMirror + JSON5 manifest parsing saturate gateway and starve event loop #73532
• Related [Bug]: Bundled plugin runtime mirror runs synchronously on every pi-agent invocation, blocking the gateway main thread for tens of seconds (regression in 2026.4.22+) #75069
• Related 2026.4.29: Gateway repeatedly spawns runtime-deps pnpm installs and starves event loop #75283
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the lazy plugin runtime-deps path only checked the full package-level plan after collecting all bundled plugin deps, so an already-materialized generated manifest still paid the all-plugin manifest scan cost.
• Missing detection / guardrail: no regression test asserted that a materialized generated package-level manifest avoids reading unrelated plugin manifests.
• Contributing context (if known): packaged installs with runtime-deps mirrors and channel/provider plugin loading make this path visible during gateway startup and control-plane operations.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/plugins/bundled-runtime-deps.test.ts
• Scenario the test should lock in: generated package-level deps are already materialized, the requested plugin loads, and unrelated plugin manifests are not read.
• Why this is the smallest reliable guardrail: it exercises the exact materialization helper path with filesystem fixtures and a read spy.
• Existing test that already covers this (if any): adjacent runtime-deps materialization tests covered reinstall avoidance, but not scan avoidance.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

None directly. This is a performance/responsiveness optimization for packaged plugin runtime-deps loading.

Diagram (if applicable)

Before:
load plugin -> scan all bundled plugin manifests -> discover generated manifest is enough -> skip install

After:
load plugin -> prove requested deps already materialized -> skip all-plugin scan and install

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local plus Blacksmith Linux Testbox
• Runtime/container: Node/pnpm via repo wrappers
• Model/provider: N/A
• Integration/channel (if any): bundled plugin runtime-deps
• Relevant config (redacted): OPENCLAW_PLUGIN_STAGE_DIR fixture

Steps

1. Create a packaged OpenClaw fixture with two bundled plugins and an external runtime-deps install root.
2. Materialize a generated package-level manifest containing both plugin deps.
3. Load one plugin and assert the other plugin manifest is not read.

Expected

• The lazy runtime-deps path returns without reinstalling and without scanning unrelated plugin manifests.

Actual

• Before this patch, the path had to collect the package-level plan first. After this patch, the fast path returns before the all-plugin scan.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: focused runtime-deps test passed locally; combined changed gate passed on Blacksmith Testbox before PR split.
• Edge cases checked: stale generated manifest and stale installed package paths remain covered by existing adjacent tests.
• What you did not verify: live Linux npm-global Telegram repro/profile.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: an incomplete package-level generated manifest could hide missing deps.
  • Mitigation: the fast path checks only the requested plugin deps plus mirrored root deps with isRuntimeDepsPlanMaterialized; stale/incomplete manifests fall through to the existing full package-level plan.