fix(update): repair configured plugins during legacy upgrades by joshavant · Pull Request #82859 · openclaw/openclaw

joshavant · 2026-05-17T03:13:17Z

Summary

Problem: upgrading from 2026.4.x to 2026.5.x could leave configured externalized channel plugins, including Discord, without installed plugin payloads.
Why it matters: the existing channel config survived but the channel appeared disabled/missing until the operator manually installed the plugin.
What changed: current update doctor passes now opt into configured-plugin repair deferral, while legacy update handoffs repair missing configured plugin installs immediately and prefer npm only in that legacy handoff when both npm and ClawHub specs exist.
What did NOT change (scope boundary): this does not change normal doctor behavior outside update handoffs, and it does not change channel list diagnostics.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes Discord channel silently disabled after 2026.4.x → 2026.5.x upgrade (externalised plugin not auto-installed) #82813
This PR fixes a bug or regression

Real behavior proof (required for external PRs)

Behavior addressed: configured Discord/Telegram/WhatsApp channel plugin installs survive a 2026.4.27 -> current package upgrade without requiring manual openclaw plugins install discord.

Real environment tested: AWS Crabbox direct-provider Linux host, provider aws, lease cbx_df0f5805c899, Docker published-upgrade-survivor lane.

Exact steps or command run after this patch:

OPENCLAW_UPGRADE_SURVIVOR_PUBLISHED_BASELINE=1 \
[email protected] \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=base \
OPENCLAW_UPGRADE_SURVIVOR_DOCKER_RUN_TIMEOUT=1800s \
OPENCLAW_SKIP_CHANNELS=1 \
pnpm test:docker:published-upgrade-survivor

Evidence after fix: Crabbox run run_40c5ff416aa2, provider aws, lease cbx_df0f5805c899, printed Upgrade survivor Docker E2E passed [email protected] scenario=base candidate=2026.5.17.

Observed result after fix: baseline [email protected] upgraded to the patched current tarball, doctor and post-upgrade survival assertions passed, gateway started, and health/status probes passed.

What was not tested: live Discord API traffic was not exercised; channel runtime startup used the upgrade-survivor lane's channel-skipping setup to focus on install/upgrade survival.

Before evidence (optional but encouraged): pre-fix AWS repro showed openclaw update post-update plugin sync made no changes and standalone doctor later reported missing configured plugin installs, including Discord.

Root Cause (if applicable)

Root cause: missing configured plugin install repair was gated on OPENCLAW_UPDATE_IN_PROGRESS, but legacy 2026.4.x updaters set only that env while running newer doctor code and do not have the newer post-core convergence phase.
Missing detection / guardrail: update-phase helpers did not distinguish current update handoffs that should defer repair from legacy handoffs that must repair immediately.
Contributing context: some externalized plugins publish both npm and ClawHub install specs, but ClawHub payloads can require a newer plugin API than the old runtime executing the legacy update handoff.

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/missing-configured-plugin-install.test.ts, src/commands/doctor/shared/update-phase.test.ts, src/commands/doctor/shared/release-configured-plugin-installs.test.ts, src/infra/update-runner.test.ts, src/cli/update-cli.test.ts.
Scenario the test should lock in: legacy update doctor repairs configured plugin installs, current update/finalize/git doctors defer to post-core convergence, and ClawHub-only candidates still work.
Why this is the smallest reliable guardrail: these tests lock the phase/env contract and installer-source selection without requiring Docker for every edit loop.
Existing test that already covers this (if any): published upgrade-survivor Docker E2E covers the reported upgrade path.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

Users upgrading from older 2026.4.x installs should keep configured externalized channel plugins installed automatically instead of needing manual plugin installation after update.

Diagram (if applicable)

Before:
2026.4.x updater -> newer doctor sees OPENCLAW_UPDATE_IN_PROGRESS -> defers repair -> plugin missing

After:
legacy updater -> newer doctor sees no explicit defer marker -> repairs configured plugin install
current updater -> newer doctor sets explicit defer marker -> post-core convergence repairs and smoke-checks

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: AWS Crabbox Linux
Runtime/container: Node 22, pnpm 11.1.0, Docker published-upgrade-survivor E2E
Model/provider: N/A
Integration/channel (if any): Discord/Telegram/WhatsApp configured channel plugin install survival
Relevant config (redacted): upgrade-survivor baseline recipe with configured channels.discord, channels.telegram, and channels.whatsapp

Steps

Install published baseline [email protected] in the upgrade-survivor container.
Seed configured channel/plugin state from the baseline recipe.
Upgrade to the patched current tarball.
Run doctor, survival assertions, gateway start, and status probes.

Expected

Missing configured plugin installs are repaired during the legacy handoff/update path, and gateway startup/status probes pass.

Actual

AWS Crabbox run_40c5ff416aa2 passed the full published upgrade-survivor lane.

Evidence

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: local focused tests; post-review AWS Crabbox 2026.4.27 -> patched current upgrade-survivor Docker E2E.
Edge cases checked: current package/finalize/git doctor deferral, legacy update repair, npm-over-ClawHub only when npm exists, ClawHub-only candidates still install.
What you did not verify: real Discord bot message delivery.

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? Yes
Migration needed? No
If yes, exact upgrade steps: no user action; current update paths set an internal defer marker, while legacy handoffs are inferred by its absence.

Risks and Mitigations

Risk: installing too early during current update flows could bypass post-core convergence.
- Mitigation: current package/finalize/git update doctor paths explicitly set the defer marker and have regression tests.
Risk: preferring npm in legacy handoff could break ClawHub-only installs.
- Mitigation: npm is preferred only when an npm spec exists; ClawHub-only behavior has regression coverage.

clawsweeper · 2026-05-17T03:14:36Z

Codex review: needs maintainer review before merge.

Summary
The PR adds an explicit update-doctor deferral marker so legacy 2026.4.x update handoffs repair missing configured externalized plugin installs immediately while current update flows still defer to post-core convergence.

Reproducibility: yes. for the source path: current main still defers configured plugin repair when a legacy updater supplies only OPENCLAW_UPDATE_IN_PROGRESS. The PR body adds stronger after-fix Crabbox upgrade-survivor proof for the packaged 2026.4.27 upgrade path.

Real behavior proof
Sufficient (live_output): The PR body includes after-fix real behavior proof from an AWS Crabbox Docker published-upgrade-survivor run for [email protected] to patched current, including run id and observed pass output.

Next step before merge
The PR has a protected maintainer label and no narrow automated repair target; the remaining action is normal maintainer merge handling after required checks.

Security
Cleared: No concrete security or supply-chain regression found; the patch changes env gating and source preference inside existing official plugin repair flows without new workflows, dependencies, secrets handling, or broader execution permissions.

Review details

Best possible solution:

Land the explicit defer-marker split after maintainer review and checks, preserving post-core convergence for current updaters while letting legacy update handoffs repair configured externalized plugins before restart.

Do we have a high-confidence way to reproduce the issue?

Yes for the source path: current main still defers configured plugin repair when a legacy updater supplies only OPENCLAW_UPDATE_IN_PROGRESS. The PR body adds stronger after-fix Crabbox upgrade-survivor proof for the packaged 2026.4.27 upgrade path.

Is this the best way to solve the issue?

Yes: the explicit defer marker is a narrow maintainable split between current update flows that have post-core convergence and legacy update handoffs that must repair immediately; the npm preference is scoped to legacy handoffs with an npm spec.

Acceptance criteria:

node scripts/run-vitest.mjs src/commands/doctor/shared/missing-configured-plugin-install.test.ts src/commands/doctor/shared/update-phase.test.ts src/commands/doctor/shared/release-configured-plugin-installs.test.ts src/infra/update-runner.test.ts src/cli/update-cli.test.ts
OPENCLAW_UPGRADE_SURVIVOR_PUBLISHED_BASELINE=1 [email protected] OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=base OPENCLAW_UPGRADE_SURVIVOR_DOCKER_RUN_TIMEOUT=1800s OPENCLAW_SKIP_CHANNELS=1 pnpm test:docker:published-upgrade-survivor

What I checked:

Current main defers configured plugin repair for legacy updater env: Current main still calls isUpdatePackageSwapInProgress(env) before skipping configured plugin install repair, so a legacy updater that sets only OPENCLAW_UPDATE_IN_PROGRESS=1 takes the deferral path. (src/commands/doctor/shared/missing-configured-plugin-install.ts:1029, 39a9a3478f11)
Update phase helper treats plain update-in-progress as package swap: isUpdatePackageSwapInProgress returns true for OPENCLAW_UPDATE_IN_PROGRESS except during explicit post-core convergence, matching the reported legacy-update failure mode. (src/commands/doctor/shared/update-phase.ts:29, 39a9a3478f11)
Current update callers do not yet set a narrower repair-defer marker: The current package and git update doctor invocations set OPENCLAW_UPDATE_IN_PROGRESS and parent config-write support, but not a configured-plugin-specific deferral signal. (src/cli/update-cli/update-command.ts:1266, 39a9a3478f11)
PR diff introduces the explicit defer contract and legacy repair tests: The PR adds OPENCLAW_UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR, shouldDeferConfiguredPluginInstallRepair, isLegacyPackageUpdateDoctorPass, marks current update/finalize/git doctor passes, and adds legacy npm/ClawHub coverage. (src/commands/doctor/shared/update-phase.ts:35, 71d64bf532d4)
Real behavior proof is present: The PR body reports AWS Crabbox published-upgrade-survivor proof for [email protected] to patched current, with run run_40c5ff416aa2, and observed doctor, survival assertions, gateway start, and health/status probes passing. (71d64bf532d4)
Related implementation history: Merged fix(update): mandatory post-core plugin convergence before gateway restart #79143 introduced the post-core plugin convergence model that this PR refines for legacy updater handoffs; merged fix(channels): show missing external channel config #82849 separately fixed the channel-list diagnostic side of the linked user report. (109493bcdd62)

Likely related people:

BKF-Gitty: Authored the merged post-core plugin convergence PR that created the update-phase helper and convergence semantics this PR adjusts for legacy updater handoffs. (role: introduced adjacent behavior; confidence: high; commits: 109493bcdd62, 6dd20534f984, 408a150b0882; files: src/commands/doctor/shared/update-phase.ts, src/commands/doctor/shared/missing-configured-plugin-install.ts, src/cli/update-cli/post-core-plugin-convergence.ts)
steipete: Authored the merged diagnostic fix for the same linked user report, covering missing external channel config display and related regression coverage. (role: recent adjacent contributor; confidence: medium; commits: b328f57bc3f7; files: src/commands/channels/list.ts, src/commands/channels.list.test.ts, src/commands/doctor/shared/missing-configured-plugin-install.test.ts)
Sunnyone2three: Local blame for the current shallow checkout attributes the visible update-phase and missing-plugin repair lines to the grafted current-main history; this is a weak routing signal compared with the linked PR history. (role: recent area contributor in local history; confidence: low; commits: 8e21b3c9a64e; files: src/commands/doctor/shared/update-phase.ts, src/commands/doctor/shared/missing-configured-plugin-install.ts)

Remaining risk / open question:

The PR proof does not exercise live Discord message traffic; it proves install/upgrade survival with channel startup skipped, which matches the main reported failure boundary.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 39a9a3478f11.

…aw#82859) * fix(update): repair configured plugins during legacy upgrades * docs(changelog): note legacy plugin upgrade repair * test(update): use valid whatsapp upgrade fixture

fix(update): repair configured plugins during legacy upgrades

db56ffe

openclaw-barnacle Bot added cli CLI command changes commands Command implementations size: M labels May 17, 2026

docs(changelog): note legacy plugin upgrade repair

edc7124

openclaw-barnacle Bot added the maintainer Maintainer-authored PR label May 17, 2026

clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. P1 High-priority user-facing bug, regression, or broken workflow. impact:message-loss Channel message delivery can be lost, duplicated, or misrouted. labels May 17, 2026

test(update): use valid whatsapp upgrade fixture

71d64bf

joshavant merged commit ab2943e into main May 17, 2026
114 checks passed

joshavant deleted the fix/legacy-configured-plugin-upgrade branch May 17, 2026 03:49

This was referenced Jun 18, 2026

[Bug]: Discord channel not loaded in 2026.5.4 (and beta.2/beta.3), works in beta.1 and 2026.4.29 #77930

Open

docs: call out discord external plugin install #78090

Open

This was referenced Jul 1, 2026

[Bug]: Container image upgrades skip openclaw upgrade migrations before gateway startup #98565

Closed

Fix container image upgrade migrations before gateway readiness #101881

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(update): repair configured plugins during legacy upgrades#82859

fix(update): repair configured plugins during legacy upgrades#82859
joshavant merged 3 commits into
mainfrom
fix/legacy-configured-plugin-upgrade

joshavant commented May 17, 2026

Uh oh!

clawsweeper Bot commented May 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

joshavant commented May 17, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Real behavior proof (required for external PRs)

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

clawsweeper Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented May 17, 2026 •

edited

Loading