PR #75071: fix(plugins): invalidate runtime deps cache on package upgrade

• Repository: openclaw/openclaw
• Author: sahilsatralkar
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/75071

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: Bundled plugin runtime-deps cache could be reused after an in-place OpenClaw package upgrade at the same filesystem path.
• Why it matters: A packaged upgrade such as 2026.4.26 -> 2026.4.27 could keep loading stale staged runtime dependencies for bundled plugins.
• What changed: The plugin loader cache key now includes bundled package identity/version metadata, and a regression test locks the upgrade scenario.
• What did NOT change (scope boundary): No runtime dependency install policy, plugin manifest format, gateway behavior, docs, or user-facing config changed.

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

• Closes #75045
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: The plugin registry cache key included bundled plugin root paths and config inputs, but did not include the owning packaged OpenClaw version/package identity. When a packaged install was upgraded in place, the path stayed stable and the stale cached registry/runtime-deps staging could be reused.
• Missing detection / guardrail: There was no regression test covering a same-path packaged upgrade where the root package version changes while bundled plugin runtime-deps should be restaged.
• Contributing context (if known): The issue was observed with stale openclaw-2026.4.26-* browser runtime-deps paths after upgrading to a newer packaged build.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• 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/loader.test.ts
  • Scenario the test should lock in: Loading a bundled plugin from the same package root before and after changing the root OpenClaw package version must not reuse the old cached registry/runtime-deps stage.
  • Why this is the smallest reliable guardrail: The bug lives at the plugin loader cache/staging seam, so the test exercises loadOpenClawPlugins with a temp bundled package and fake runtime-deps install without requiring a full packaged app install.
  • Existing test that already covers this (if any): None.
  • If no new test is added, why not: N/A.

User-visible / Behavior Changes

Packaged OpenClaw upgrades should no longer keep using stale bundled plugin runtime-deps staging from the previous package version.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

  Before:
  [upgrade package in place] -> [same bundled plugin path] -> [old loader cache key] -> [stale runtime deps reused]

  After:
  [upgrade package in place] -> [package version identity changes] -> [new loader cache key] -> [fresh runtime deps
  staging]

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): Bundled plugin runtime-deps loader
• Relevant config (redacted): OPENCLAW_BUNDLED_PLUGINS_DIR, OPENCLAW_PLUGIN_STAGE_DIR, OPENCLAW_TEST_TRUST_BUNDLED_PLUGINS_DIR=1

Steps

1. Load a bundled plugin from a packaged root with root package version 2026.4.26.
2. Mutate the same package root to version 2026.4.27 and update the bundled plugin runtime entry.
3. Load the same bundled plugin again.

Expected

• The second load computes a distinct cache key and uses fresh runtime-deps staging for the upgraded package version.

Actual

• Before this fix, the second load could reuse the first cached plugin registry/runtime-deps staging because the package version was not part of the cache identity.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • New regression failed before the implementation change and passed after it.
  • Targeted plugin loader/runtime-deps tests passed.
  • Targeted doctor/gateway runtime-deps tests passed.
  • Targeted formatter check passed.
  • pnpm build passed.
  • codex review --base origin/main completed with no findings.
• Edge cases checked:
  • Same package path with changed root package version.
  • Runtime-deps install root changes after upgrade.
  • Existing bundled runtime-deps/stage-root/persisted manifest coverage remains green.
• What you did not verify:
  • Broad Blacksmith/Testbox changed-gate was not run.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

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

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: Cache invalidation becomes slightly broader for packaged bundled plugin roots when package metadata changes.
  • Mitigation: The cache identity is scoped to the bundled package root/package.json metadata and does not change runtime dependency install policy or plugin contracts.

Changed files

• src/plugins/loader.test.ts (modified, +129/-0)
• src/plugins/loader.ts (modified, +68/-0)