docs: propose plugin update availability

[ekinnee]

What Problem This Solves

Formalizes Erick Kinnee's proposal to surface installed-plugin update availability in CLI inventory, update status, and Control UI.

Related: openclaw/openclaw#131897

Why This Change Was Made

Proposes ClawHub as the primary metadata path while preserving recorded npm sources. Defines explicit plugin refresh, shared SQLite observation ownership, 24-hour freshness, four concurrent lookups, a 15-second network budget, and JSON distinctions for eligible, excluded, stale, and unknown results. Core upgrades invalidate cached eligibility. Metadata checks must not enter installer dry-run paths.

These defaults and persistence semantics are proposed for maintainer acceptance. Exact schema, migration, and publication fencing require storage-owner review before implementation. Upgrade preflight remains separate: openclaw/openclaw#122019.

User Impact

Proposal only; no runtime behavior changes. If accepted and implemented, operators could discover plugin updates while preserving pins and distinguishing incomplete checks.

Evidence

• Parsed YAML frontmatter: status remains draft and implementation issue remains blank.
• Verified all seven required RFC sections against the repository template.
• Rendered the revised Markdown to HTML with markdown-it; no browser visual inspection or screenshot is claimed.
• Verified the original proposal, upgrade-preflight issue, and RFC PR links through live GitHub reads.
• Whitespace validation produced no diagnostics.
• Bounded independent contract review identified host-version cache invalidation, now included.
• No runtime implementation, runtime proof, or upgrade-compatibility verdict is claimed.

The required maintainer-discussion thread and RFC acceptance remain outstanding. A maintainer sponsor is needed to advance that discussion.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 9, 2026, 7:47 PM ET / 23:47 UTC (Revision 4).

ClawSweeper review

What this changes

Adds an RFC proposing plugin update notices across CLI inventory, update status, and Control UI, with explicit refresh, preserved pins, and shared retained observations.

Merge readiness

⛔ Blocked before merge - 4 items remain

Keep open: this is a coherent, distinct RFC with no verified merged replacement. Repository lifecycle approval and the prior document-verification request remain outstanding; no actionable patch defect was found.

Priority: P3
Reviewed head: eb7d01d73d9555d1280b1ac5cae9d0c8b28d8607
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The proposal is focused and internally coherent, but the reported document checks lack inspectable results.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: Needs document-verification proof before merge: the captured body reports rendering and link checks without observable output or an artifact, leaving the prior same-head request unresolved. The changed owner is the RFC document, so evidence should show its rendering and links, not unimplemented plugin runtime behavior; rfcs/ does not meet the literal docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: Needs document-verification proof before merge: the captured body reports rendering and link checks without observable output or an artifact, leaving the prior same-head request unresolved. The changed owner is the RFC document, so evidence should show its rendering and links, not unimplemented plugin runtime behavior; rfcs/ does not meet the literal docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Verified proposal-only scope: The complete introduced patch adds one 231-line Markdown RFC. It proposes metadata-only checks and explicitly defers schema, migration, publication fencing, and acceptance; it introduces no executable implementation. RFC acceptance is required before merge: README requires a maintainer-discussion thread, acceptance, and a linked implementation issue before merging. The submitted frontmatter correctly remains draft with its implementation issue blank, and the captured PR body acknowledges that discussion and acceptance remain outstanding. Current-main and canonical search: The pinned main tree lacks this RFC. Whole-tree searches found no equivalent availability proposal; the GitHub pull-request listing returned related plugin proposals but no matching merged replacement. The repository release endpoint returned an empty list.
Findings	None	None.
Security	None	None.

How this fits together

This repository stores OpenClaw design proposals for discussion and acceptance before implementation. The proposed plugin availability view would turn recorded installations and registry metadata into consistent CLI and Control UI notices.

flowchart TD
  A[Recorded plugin installations] --> C[Proposed metadata resolver]
  B[Explicit authorized refresh] --> C
  C --> D[Registry metadata]
  D --> E[Retained availability observations]
  E --> F[CLI inventory and status]
  E --> G[Control UI notices]

Loading

Decision needed

Question	Recommendation
Should this RFC advance with explicit plugin refresh and shared SQLite observations under the proposed v1 contract?	Advance through RFC discussion: Sponsor discussion of the proposed v1 contract and record acceptance or specific amendments before implementation.

Why: The repository requires RFC acceptance, and the proposed command, retention policy, and storage ownership need product agreement rather than mechanical correction.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: Needs document-verification proof before merge: the captured body reports rendering and link checks without observable output or an artifact, leaving the prior same-head request unresolved. The changed owner is the RFC document, so evidence should show its rendering and links, not unimplemented plugin runtime behavior; rfcs/ does not meet the literal docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - Acceptance of the proposed refresh interface, freshness limits, and shared persistence ownership remains unresolved; exact storage design is explicitly deferred to implementation review.
• Complete next step (P2) - Complete the required maintainer discussion and record acceptance before merging; after acceptance, link the implementation issue and update RFC status.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

None.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Adopt a maintainer-approved, source-preserving availability contract that keeps inventory local and distinguishes eligible, pinned, stale, and unknown results.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Adopt a maintainer-approved, source-preserving availability contract that keeps inventory local and distinguishes eligible, pinned, stale, and unknown results.

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

Not applicable: this PR proposes a new availability view and refresh flag rather than repairing an established behavior contract.

Is this the best way to solve the issue?

Yes at the architectural level: sharing metadata resolution while preserving sources and pins avoids competing selection logic; the exact refresh and persistence contract still needs acceptance.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 967d9aac7472.

Labels

Label justifications:

• P3: This proposal improves update discoverability without changing runtime behavior or establishing an urgent broken workflow.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: Needs document-verification proof before merge: the captured body reports rendering and link checks without observable output or an artifact, leaving the prior same-head request unresolved. The changed owner is the RFC document, so evidence should show its rendering and links, not unimplemented plugin runtime behavior; rfcs/ does not meet the literal docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Verified proposal-only scope: The complete introduced patch adds one 231-line Markdown RFC. It proposes metadata-only checks and explicitly defers schema, migration, publication fencing, and acceptance; it introduces no executable implementation. (rfcs/0065-plugin-update-availability.md:117, eb7d01d73d95)
• RFC acceptance is required before merge: README requires a maintainer-discussion thread, acceptance, and a linked implementation issue before merging. The submitted frontmatter correctly remains draft with its implementation issue blank, and the captured PR body acknowledges that discussion and acceptance remain outstanding. (README.md:80, 967d9aac7472)
• Current-main and canonical search: The pinned main tree lacks this RFC. Whole-tree searches found no equivalent availability proposal; the GitHub pull-request listing returned related plugin proposals but no matching merged replacement. The repository release endpoint returned an empty list. (967d9aac7472)
• RFC process routing history: Local README history identifies the RFC process and sidecar-layout changes. GitHub commit metadata confirms kevinslin for e366ea9 and RomneyDa for 3aa7d72. Some local historical blob reads failed; routing therefore uses API-confirmed commit context without claiming verified source-line introduction. (README.md:78, e366ea9825a4)
• Original request remains paired with this RFC: RFC: Surface plugin update availability in plugins list / update status / Control UI openclaw#131897 remains open and requests the same installed-plugin availability surfaces. Its discussion recognizes the active RFC and distinguishes existing pin notices from the proposed inventory/status presentation. This is discussion evidence, not independent runtime verification.
• Upgrade preflight is distinct work: [Bug]: openclaw update status omits configured-plugin availability and irreversible migration risk openclaw#122019 requests candidate-core compatibility and irreversible-migration assessment before mutation. The RFC explicitly excludes that broader admission decision.

Likely related people:

• kevinslin: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• RomneyDa: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach a rendered-RFC screenshot or verification transcript showing formatting and link results, redacting private information; update the PR body for automatic re-review, or ask a maintainer to comment @clawsweeper re-review.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-09-06T21:37:37.741Z sha 8835147 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-07T21:01:18.885Z sha 8835147 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-07T21:20:08.753Z sha eb7d01d :: needs real behavior proof before merge. :: none