Fix plugin packaging recovery hints#86591
Conversation
|
Codex review: needs maintainer review before merge. Reviewed May 25, 2026, 7:48 PM ET / 23:48 UTC. Summary PR surface: Source +128, Tests +333. Total +461 across 14 files. Reproducibility: yes. Current main source still appends generic doctor hints on invalid-config startup and guard paths, while plugin discovery can emit a compiled-runtime-output packaging diagnostic plus same-plugin plugin-not-found fallout; I did not rerun live commands in this read-only review. Review metrics: 1 noteworthy metric.
Merge readiness Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch. Rank-up moves:
Risk before merge
Maintainer options:
Next step before merge Security Review detailsBest possible solution: Land after current-head CI passes, keeping installed package loading strict and preserving doctor guidance for ordinary invalid configs while using packaging-specific remediation for compiled-runtime-output plugin failures. Do we have a high-confidence way to reproduce the issue? Yes. Current main source still appends generic doctor hints on invalid-config startup and guard paths, while plugin discovery can emit a compiled-runtime-output packaging diagnostic plus same-plugin plugin-not-found fallout; I did not rerun live commands in this read-only review. Is this the best way to solve the issue? Yes. The PR keeps third-party installed package loading strict and fixes only recovery-hint selection across the affected CLI and gateway surfaces, with tests preserving doctor guidance for ordinary invalid config. AGENTS.md: found and applied where relevant. Codex review notes: model gpt-5.5, reasoning high; reviewed against 719ce7f96f42. Label changesLabel changes:
Label justifications:
Evidence reviewedPR surface: Source +128, Tests +333. Total +461 across 14 files. View PR surface stats
What I checked:
Likely related people:
What the crustacean ranks mean
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics. How this review workflow works
|
|
ClawSweeper PR egg ✨ Hatched: 🥚 common Frosted Proofling Hatch commandComment Hatchability rules:
Rarity: 🥚 common. What is this egg doing here?
|
|
@clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
|
@clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
aa1cb07 to
b2448ac
Compare
b2448ac to
3b3ce73
Compare
|
Maintainer update before landing: Behavior addressed: source-only installed plugin packages now report a plugin packaging remediation instead of sending users to openclaw doctor --fix. Real environment tested: Blacksmith Testbox through Crabbox on Linux, plus focused local Vitest shards. Exact steps or command run after this patch:
Evidence after fix:
Observed result after fix: both config validate and gateway startup fail with plugin not found: source-only-pack, include the plugin packaging guidance, and omit openclaw doctor --fix. What was not tested: no live third-party plugin package was fetched from npm; the E2E used a disposable local installed-package fixture to reproduce the reported packaging shape. |
Summary
What problem does this PR solve?
openclaw doctor --fixrecovery hint.Why does this matter now?
What is the intended outcome?
openclaw doctor --fix.What is intentionally out of scope?
What does success look like?
What should reviewers focus on?
src/config/recovery-policy.ts, especially that it only suppresses doctor guidance for compiled-runtime-output packaging diagnostics and same-pluginplugin not foundfallout.Summary guidance
This PR description is the contributor's durable explanation of the change. Write it for human maintainers first; ClawSweeper and Barnacle use the same text to understand intent, proof, risk, and current review state.
Describe the intent and outcome in 2-5 bullets. Avoid restating the diff; reviewers and bots can read the changed files.
If this PR fixes a plugin beta-release blocker, title it
fix(<plugin-id>): beta blocker - <summary>and link the matchingBeta blocker: <plugin-name> - <summary>issue labeledbeta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.Linked context
Which issue does this close?
Closes #80490
Which issues, PRs, or discussions are related?
Related: ClawSweeper guidance in #80490 (comment)
Was this requested by a maintainer or owner?
ClawSweeper guidance requested a focused repair that corrects startup/config guidance without auto-building third-party plugin source.
Linked context guidance
Link the issue, PR, discussion, maintainer request, or owner request that explains why this PR should exist. Maintainer context helps reviewers and automation distinguish intended work from drive-by churn.
Real behavior proof (required for external PRs)
openclaw doctor --fix.openclaw-issue-80490-proof:local, providerlocal-container, leasecbx_0b5f611fb5a6, slugsilver-shrimp.@openclaw/source-only-packpackage whose manifest points at./index.tsand no compiled JS, wrote config withplugins.slots.memory="source-only-pack", then ranpnpm openclaw config validateandtimeout 30s pnpm openclaw gateway run.openclaw doctor --fixwas absent from both outputs.--no-syncand a disposable Docker image containing the patched checkout to keep the proof in a real Linux/container lane without touching live runtime state.formatInvalidConfigRecoveryHint()for this failure shape before the patch.Real behavior proof guidance
External contributors must show after-fix evidence from a real OpenClaw setup. Unit tests, mocks, lint, typechecks, snapshots, and CI are supplemental only.
Screenshots are encouraged even for CLI, console, text, or log changes. Terminal screenshots, copied live output, redacted runtime logs, recordings, and linked artifacts count.
If your environment cannot produce the ideal proof, explain that under
Proof limitations or environment constraintsso reviewers and ClawSweeper can direct the next step properly.Be mindful of private information like IP addresses, API keys, phone numbers, non-public endpoints, or other private details when providing evidence.
Tests and validation
Which commands did you run?
What regression coverage was added or updated?
openclaw doctor --fixis absent for source-only installed plugin packaging failures.What failed before this fix, if known?
openclaw doctor --fixfor this packaging failure shape.If no test was added, why not?
Testing guidance
List focused commands, not every incidental check. CI is useful support, but external PRs still need real behavior proof above when behavior changes.
Risk checklist
Did user-visible behavior change? (
Yes/No)Yes.
Did config, environment, or migration behavior change? (
Yes/No)No config schema or migration behavior changed; only recovery guidance selection changed.
Did security, auth, secrets, network, or tool execution behavior change? (
Yes/No)No.
What is the highest-risk area?
Over-suppressing the generic doctor hint for mixed or unrelated invalid configs.
How is that risk mitigated?
The classifier requires a compiled-runtime-output plugin packaging diagnostic and only permits same-plugin
plugin not foundfallout; tests cover mixed core invalidity and unrelated missing plugins retaining doctor guidance.Risk guidance
Use this for author judgment that is not obvious from the diff. ClawSweeper can see touched files, but it cannot know which behavior you think is risky, why the risk is acceptable, or what mitigation reviewers should verify.
Current review state
What is the next action?
Review and CI.
What is still waiting on author, maintainer, CI, or external proof?
CI is pending after PR creation; external proof is included above.
Which bot or reviewer comments were addressed?
Addresses ClawSweeper guidance on #80490 by correcting diagnostics/recovery hints rather than auto-building third-party plugin source.
Review state guidance
Keep this as the durable state for review progress. If useful information appears in comments, fold the current next action or blocker back here so maintainers and ClawSweeper do not need to reconstruct state from comment history.