PR #77464: fix(plugins): recover managed-npm external plugins after package-manager upgrade

• Repository: openclaw/openclaw
• Author: p3nchan
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/77464

Description (problem / solution / changelog)

Repro

1. Install external plugins such as @openclaw/whatsapp on 2026.5.2.
2. Upgrade OpenClaw directly through the package manager, e.g. pnpm add -g openclaw@latest, rather than openclaw update.
3. Restart the gateway.
4. openclaw status, openclaw channels status, and openclaw plugins list can stop showing the external plugin even though the managed package still exists under the OpenClaw npm root.

Root cause

src/plugins/plugin-registry-snapshot.ts could return the persisted registry fast path before asking the managed npm install-record reader whether recoverable packages existed under the OpenClaw-owned npm root. When the persisted snapshot was already stale, that let the missing external plugin stay hidden.

If the loader did fall through to the derived path, it still forced installRecords from the persisted snapshot into loadInstalledPluginIndex, which bypassed the default loadInstalledPluginIndexInstallRecordsSync reader and skipped the managed-npm recovery records.

Fix

• Add a fast-path stale-source guard in plugin-registry-snapshot.ts that loads install records through the existing reader and invalidates the persisted registry when recovered managed-npm records are absent from the persisted plugin snapshot.
• Stop forcing persisted install records on the normal derived path, so loadInstalledPluginIndex can use its default reader and merge recovered managed-npm records.
• Preserve the OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY break-glass behavior by still passing {} when persisted install-record reads are disabled.
• Keep the existing persisted-record precedence semantics in installed-plugin-index-record-reader.ts unchanged.

Startup cost

This does not run npm, pnpm, installs, or any network operation on startup. The new guard only performs the same cheap managed npm root metadata reads already used by loadInstalledPluginIndexInstallRecordsSync, and only after the other persisted-registry staleness checks pass.

Test coverage

• src/plugins/plugin-registry-snapshot.test.ts: stale persisted registry plus hermetic stateDir/npm/package.json and node_modules/@openclaw/whatsapp recovers through the derived snapshot with persisted-registry-stale-source.
• src/plugins/status.registry-snapshot.test.ts: buildPluginRegistrySnapshotReport keeps the recovered WhatsApp plugin visible, matching the openclaw plugins list surface.
• Existing src/plugins/installed-plugin-index-records.test.ts continues to cover reader-level managed npm recovery and persisted-record precedence.

Validation

• pnpm test src/plugins/plugin-registry-snapshot.test.ts src/plugins/installed-plugin-index-records.test.ts src/plugins/status.registry-snapshot.test.ts ✅
• pnpm test src/cli/update-cli/update-command.test.ts ✅
• pnpm exec oxfmt --check --threads=1 src/plugins/plugin-registry-snapshot.ts src/plugins/plugin-registry-snapshot.test.ts src/plugins/status.registry-snapshot.test.ts CHANGELOG.md ✅
• pnpm check:changed currently fails in upstream typecheck on untouched src/plugins/session-entry-slot-keys.ts:113 (MissingSessionEntryReservedSlotKeys includes "pendingFinalDelivery"). Earlier check:changed lanes passed: conflict markers, changelog attributions, extension wildcard re-exports, plugin-sdk wildcard re-exports, duplicate scan target coverage, and runtime sidecar loader guard.

Fixes #77266

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/plugins/plugin-registry-snapshot.test.ts (modified, +110/-0)
• src/plugins/plugin-registry-snapshot.ts (modified, +39/-3)
• src/plugins/status.registry-snapshot.test.ts (modified, +111/-0)

PR #77604: fix(update): restore configured plugins on 4-to-5 updates

• Repository: openclaw/openclaw
• Author: Patrick-Erichsen
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77604

Description (problem / solution / changelog)

Summary

• Problem: updating from 2026.4.x to 2026.5.x externalized official plugins, but configured channel/provider plugins were not automatically restored during openclaw update.
• Why it matters: previously working channels such as WhatsApp could disappear until the operator manually ran repair commands.
• What changed: package update post-core work now runs the shared configured-plugin install repair only for 2026.4.x -> 2026.5.x, before restart/status proof, and Package Acceptance asserts the repair happens before doctor --fix.
• What did NOT change (scope boundary): no startup/postinstall install behavior, no ordinary doctor behavior change, no plugins.allow-only repair, and no 2026.5.x -> 2026.5.x preservation work.

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 #77483
• Related #77266
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the 2026.5 line externalized official plugins that were bundled in 2026.4, but openclaw update only deferred configured missing-plugin repair to a later doctor pass.
• Missing detection / guardrail: Package Acceptance ran doctor --fix after update, so it did not prove update alone restored the externalized configured plugin.
• Contributing context: the 5.x already-external installed-plugin preservation bug is tracked separately in #77266 and remains out of this migration gate.

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/commands/doctor/shared/release-configured-plugin-installs.test.ts, src/cli/update-cli.test.ts, test/scripts/docker-e2e-plan.test.ts, scripts/e2e/lib/upgrade-survivor/run.sh
• Scenario the test should lock in: package update from 2026.4.x to 2026.5.x repairs missing configured official plugins before the explicit post-update doctor pass.
• Why this is the smallest reliable guardrail: unit tests lock the version/package gate and disabled-state preservation; Package Acceptance locks the installable package behavior.
• Existing test that already covers this (if any): partial doctor repair coverage existed, but update-before-doctor coverage did not.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

openclaw update now automatically installs missing configured official plugins during the 2026.4.x -> 2026.5.x package migration. Disabled plugins/channels stay disabled, global plugin disablement still skips repair, and plugins.allow-only references are not installed.

Diagram (if applicable)

Before:
openclaw update 2026.4.x -> 2026.5.x -> configured plugin missing -> user must run doctor/install

After:
openclaw update 2026.4.x -> 2026.5.x -> configured plugin repair -> restart/status proof

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) Yes
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: during the narrow 2026.4.x -> 2026.5.x package update migration, OpenClaw may install missing configured official plugins through the existing trusted catalog/doctor repair path. The version gate, package-update-only flag, disabled-state checks, and official catalog resolution keep the behavior bounded.

Repro + Verification

Environment

• OS: macOS local targeted tests; Blacksmith Testbox for changed gate
• Runtime/container: Node/pnpm repo test wrappers; Testbox ci-check-testbox.yml
• Model/provider: N/A
• Integration/channel (if any): official configured plugin migration, represented by Brave/Matrix Package Acceptance fixture coverage
• Relevant config (redacted): configured plugin/channel entries only; no live secrets

Steps

1. Seed a 2026.4.x baseline with configured official plugin usage.
2. Run openclaw update to the candidate package.
3. Assert the missing configured official plugin is installed before openclaw doctor --fix.

Expected

• The missing official plugin is restored during openclaw update.
• Disabled plugin/channel config is preserved and not installed.
• The migration repair does not run for source/git updates or non-2026.4.x -> 2026.5.x package updates.

Actual

• Verified by targeted unit/planner tests and Testbox changed gate.

Evidence

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

Human Verification (required)

• Verified scenarios:
  • pnpm test src/commands/doctor/shared/release-configured-plugin-installs.test.ts src/cli/update-cli.test.ts test/scripts/docker-e2e-plan.test.ts -- --reporter=verbose
  • pnpm test test/scripts/package-acceptance-workflow.test.ts -- --reporter=verbose
  • pnpm check:docs
  • pnpm exec oxfmt --check --threads=1 src/infra/update-runner.ts src/commands/doctor/shared/release-configured-plugin-installs.ts src/commands/doctor/shared/release-configured-plugin-installs.test.ts src/cli/update-cli/update-command.ts src/cli/update-cli.test.ts scripts/lib/docker-e2e-plan.mjs test/scripts/docker-e2e-plan.test.ts scripts/e2e/lib/upgrade-survivor/assertions.mjs
  • git diff --check
  • Testbox pnpm check:changed: https://github.com/openclaw/openclaw/actions/runs/25349362924
• Edge cases checked: disabled config preservation, plugins.allow exclusion, package-update-only guard, 2026.5.x -> 2026.5.x skip, source/git skip.
• What you did not verify: full Package Acceptance Docker lane execution against a real package artifact in this turn.

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/No) Yes
• Config/env changes? (Yes/No) No user-facing config changes
• Migration needed? (Yes/No) Yes, automatic only for 2026.4.x -> 2026.5.x package updates
• If yes, exact upgrade steps: run openclaw update; no extra manual doctor/install command should be required for missing configured official plugins in this migration path.

Risks and Mitigations

• Risk: package update performs an automatic plugin install during a migration.
  • Mitigation: restricted to package updates with 2026.4.x -> 2026.5.x, official configured plugin usage only, existing trusted catalog install paths, and disabled/deny/global-disable checks.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/ci.md (modified, +1/-1)
• docs/help/testing-updates-plugins.md (modified, +5/-1)
• docs/help/testing.md (modified, +1/-1)
• docs/reference/RELEASING.md (modified, +2/-1)
• docs/reference/test.md (modified, +1/-1)
• scripts/e2e/lib/upgrade-survivor/assertions.mjs (modified, +2/-0)
• scripts/e2e/lib/upgrade-survivor/run.sh (modified, +8/-1)
• scripts/lib/docker-e2e-plan.mjs (modified, +22/-5)
• src/cli/update-cli.test.ts (modified, +77/-0)
• src/cli/update-cli/update-command.ts (modified, +79/-2)
• src/commands/doctor/shared/release-configured-plugin-installs.test.ts (modified, +134/-0)
• src/commands/doctor/shared/release-configured-plugin-installs.ts (modified, +74/-3)
• src/infra/update-runner.ts (modified, +5/-0)
• test/scripts/docker-e2e-plan.test.ts (modified, +31/-3)