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

Document verification performed October 6, 2026 (America/Chicago; UTC timestamp below), against unchanged head eb7d01d73d9555d1280b1ac5cae9d0c8b28d8607.

The transcript below is the public reviewable evidence requested by ClawSweeper. It verifies the RFC document, not the future runtime implementation. Source: rendered RFC at the verified commit.

Method: extract the exact Git blob with git show HEAD:rfcs/0065-plugin-update-availability.md; parse its frontmatter using PyYAML; compare metadata keys and H2 headings with rfcs/0000-template.md at the base commit; render the body with markdown-it-py CommonMark and table support; parse the resulting HTML and compare heading/list counts to source; resolve every explicit document URL through gh api; run git diff --check BASE...HEAD. The SHA256 below identifies the exact extracted document bytes.

A local HTML rendering was captured using headless Chrome at 1200×9000 and visually inspected. Heading hierarchy, bullets, inline code and both body links appear intact, with no visible clipping. The RFC contains no tables, diagrams, images or fenced blocks. The local screenshot and verification script are retained as task artifacts; the transcript is embedded here so public review does not depend on local filesystem access. This does not claim inspection of GitHub's rendered appearance. All three links resolved via authenticated GitHub REST reads; anonymous browser HTTP access was not tested.

Captured exact-commit document-verification transcript

UTC: 2026-10-07T01:21:27.668451+00:00
Source commit: eb7d01d73d9555d1280b1ac5cae9d0c8b28d8607
Base commit: 967d9aac74727bc9c3aded5defa976d1416d23ba
Document: rfcs/0065-plugin-update-availability.md
Document SHA256: f51ab6de3f310a922a3e20e072e0275b0125065be4ae8ff5e8de5efd665062ae
Diff: rfcs/0065-plugin-update-availability.md | 231 ++++++++++++++++++++++++++++++++
 1 file changed, 231 insertions(+)
YAML (PyYAML 6.0.2): PASS
Required keys: title, authors, created, last_updated, status, issue, rfc_pr
Values: {"title": "Surface plugin update availability", "authors": ["Erick Kinnee (@ekinnee)"], "created": "2026-08-28", "last_updated": "2026-09-07", "status": "draft", "issue": null, "rfc_pr": "https://github.com/openclaw/rfcs/pull/66"}
Required sections: PASS (7/7, template order)
H2: Summary | Motivation | Goals | Non-Goals | Proposal | Rationale | Unresolved questions
Markdown render (markdown-it-py 3.0.0, CommonMark + tables): PASS
HTML elements: {"a": 2, "code": 45, "h1": 1, "h2": 7, "h3": 5, "li": 24, "p": 24, "ul": 4}
Rendered headings: [["h1", "Proposal: Surface plugin update availability"], ["h2", "Summary"], ["h2", "Motivation"], ["h2", "Goals"], ["h2", "Non-Goals"], ["h2", "Proposal"], ["h3", "Shared availability view"], ["h3", "CLI presentation"], ["h3", "Control UI presentation"], ["h3", "Refresh and storage"], ["h3", "Acceptance criteria"], ["h2", "Rationale"], ["h2", "Unresolved questions"]]
Formatting: 1 H1, 7 H2, 5 H3, 4 unordered lists / 24 items, inline code and 2 body hyperlinks retained.
Tables/diagrams/images/fenced blocks: 0 in source; no such rendering claimed.
Visual inspection: local Chrome screenshot inspected; headings, lists, inline code and links appear intact without visible clipping. This is a local Markdown render, not the GitHub renderer.
LINK PASS: https://github.com/openclaw/openclaw/issues/122019; gh api repos/openclaw/openclaw/issues/122019; exit=0; number=122019; state=open; title=[Bug]: `openclaw update status` omits configured-plugin availability and irreversible migration risk
LINK PASS: https://github.com/openclaw/openclaw/issues/131897; gh api repos/openclaw/openclaw/issues/131897; exit=0; number=131897; state=open; title=RFC: Surface plugin update availability in `plugins list` / `update status` / Control UI
LINK PASS: https://github.com/openclaw/rfcs/pull/66; gh api repos/openclaw/rfcs/pulls/66; exit=0; number=66; state=open; title=docs: propose plugin update availability
Link scope: 3/3 explicit document URLs resolved with authenticated GitHub REST reads; anonymous browser HTTP access not tested.
git diff --check BASE...HEAD: PASS (exit=0; no diagnostics)
Runtime implementation/proof: not applicable; document proposal only. RFC draft and blank implementation issue preserved.

Remaining acceptance gates

The RFC frontmatter remains status: draft with a blank implementation issue. The required maintainer-discussion thread and sponsorship, product acceptance or amendment of the v1 contract, and subsequent implementation issue remain outstanding. Acceptance must precede accepted frontmatter and merge, per the repository README. This PR's ready-for-review UI state is not RFC acceptance.

Document verification cannot settle the proposed refresh/presentation contract, shared SQLite persistence, schema/migration/publication fencing, SDK compatibility or runtime behavior. Storage-owner and implementation review remain prerequisites. No runtime implementation, runtime proof, upgrade-compatibility verdict, RFC acceptance or merge is claimed.

[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: blocked before merge.

What this changes

Adds a draft RFC for plugin update indicators across CLI inventory, update status, and Control UI using explicit refresh and shared observations.

Example: An installed @openclaw/omniroute plugin receives a maintenance release.

• Before: The linked proposal describes operators discovering releases through explicit plugin update commands.
• After: If accepted and implemented, CLI and UI notices would distinguish eligible updates, releases outside pins, and incomplete checks.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The document has sufficient scoped proof and no concrete defect, while readiness remains limited by unresolved product acceptance.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The supplied exact-head terminal transcript demonstrates the changed RFC's metadata, required sections, Markdown rendering, links, and whitespace; runtime authorization and upgrade proof belong to subsequent implementation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Feature · Worth it: Needs a maintainer decision
User problem: Operators can miss independently released plugin maintenance updates unless they initiate an update check.
Reason: The proposal addresses a concrete discoverability problem, but its new refresh flag, JSON contract, persistence, and presentation scope remain expressly unaccepted.

Merge readiness

⛔ Blocked before merge - 2 items remain

Keep this PR open for a product decision: the draft RFC is absent from the default branch, remains paired with an open proposal by the same author, and has no concrete patch defect.

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

Decision needed

• Question: Should v1 adopt explicit refresh and shared SQLite observations across CLI and Control UI, or start with a narrower CLI-only availability check?
• Recommendation: Discuss the shared contract: Accept or amend the proposed cross-surface contract through the RFC lifecycle, then define implementation slices with storage-owner review.
• Why: The draft introduces product and persistence choices that existing commands do not establish, and neither the live discussion nor prior review records owner acceptance.

Before merge

• Complete next step - Establish the README-required maintainer-discussion thread; after acceptance, create the implementation issue and set accepted frontmatter before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

None.

Agent review details

How this fits together

This repository records design decisions rather than runtime implementations; the proposed update owner would resolve recorded plugin sources and supply retained availability observations to CLI and Control UI consumers.

flowchart LR
  A[Installed plugin records] --> B[Shared metadata resolver]
  C[Explicit authorized refresh] --> B
  D[Package registries] --> B
  B --> E[Retained availability observations]
  E --> F[CLI inventory and status]
  E --> G[Control UI notices]

Loading

Technical review

Best possible solution:

Accept or narrow one metadata-only availability contract that preserves sources and pins, exposes incomplete checks, and supplies consistent CLI and UI notices.

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

A bug reproduction is not applicable: this PR adds a proposal, and its document verification makes no claim of exercising a future runtime implementation.

Is this the best way to solve the issue?

Reusing one metadata-only resolver while preserving install sources and pins is sound, but the proposed refresh interface and shared persistence need owner acceptance before implementation.

AGENTS.md: not found in the target repository.

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

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Verified introduced change: The pinned introduction diff adds only this 231-line Markdown RFC; no executable code, schema, dependencies, or automation changes. (rfcs/0065-plugin-update-availability.md:1, eb7d01d73d95)
• RFC acceptance lifecycle: README requires a maintainer-discussion thread and acceptance before creating the implementation issue, setting accepted frontmatter, and merging; this RFC correctly remains draft with its implementation issue blank. (README.md:78, 967d9aac7472)
• Explicitly unresolved product contract: The draft requests acceptance or amendment of refresh, freshness, concurrency, network budget, JSON semantics, and shared persistence ownership; schema and migration approval are deferred to implementation. (rfcs/0065-plugin-update-availability.md:217, eb7d01d73d95)
• Default-branch and replacement search: The default-branch inventory lacks this RFC. The hosted-feeds RFC discusses catalog metadata and update notices but does not establish this installed-plugin refresh and presentation contract; the focused all-state title search identifies no replacement. (rfcs/0009-hosted-feeds-for-plugins-and-skills.md:18, 967d9aac7472)
• Document proof and review continuity: The complete live PR body contains an exact-head transcript covering frontmatter, template sections, local Markdown rendering, links, and whitespace. It expressly leaves RFC acceptance outstanding. The prior review at this unchanged head listed no findings; live reviews contain no owner approval. (rfcs/0065-plugin-update-availability.md:1, eb7d01d73d95)
• RFC process ownership history: Path history identifies the lifecycle change, and GitHub commit metadata and its patch verify kevinslin authored the acceptance requirements. Local historical blame could not read an older README blob; the REST patch independently establishes this policy contribution. (README.md:80, e366ea9825a4)

Review metrics

Metric	Value	Why it matters
Change scope	RFC +231 lines; production +0; tests +0	The addition specifies behavior and acceptance criteria without implementing runtime or persistent-state changes.

Labels

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P3: This is a design proposal for update discoverability without an introduced runtime failure or blocked existing workflow.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

History

Review history (7 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
• reviewed 2026-09-09T23:47:02.530Z sha eb7d01d :: needs real behavior proof before merge. :: none
• reviewed 2026-10-03T07:51:55.985Z sha eb7d01d :: needs real behavior proof before merge. :: none
• reviewed 2026-10-07T01:27:30.609Z sha eb7d01d :: blocked before merge. :: none
• reviewed 2026-10-07T22:54:57.973Z sha eb7d01d :: blocked before merge. :: none

Reviewed October 13, 2026, 1:54 AM ET / 05:54 UTC (Revision 8).

[ekinnee]

@Patrick-Erichsen This goes with openclaw/openclaw#131897, not sure what I need to do here if anything.