Skip to content

fix(plugins): refresh stale source plugin registry (#96046)#96080

Open
tangtaizong666 wants to merge 4 commits into
openclaw:mainfrom
tangtaizong666:fix/global-source-plugin-index-96046
Open

fix(plugins): refresh stale source plugin registry (#96046)#96080
tangtaizong666 wants to merge 4 commits into
openclaw:mainfrom
tangtaizong666:fix/global-source-plugin-index-96046

Conversation

@tangtaizong666

@tangtaizong666 tangtaizong666 commented Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What Problem This Solves

Fixes #96046.

When a persisted plugin registry already exists, Gateway validation can reuse it without noticing that a configured plugin has since been added under the auto-discovered global extensions root ($OPENCLAW_STATE_DIR/extensions). That leaves plugins.slots.memory validating against stale knownIds and reporting plugin not found even though plugin discovery can find the same plugin.

Why This Change Was Made

This change treats the persisted registry as stale only when all of these are true:

  • the user config references the plugin through plugins.entries, plugins.allow, or plugins.slots
  • the persisted index does not contain that plugin id
  • a matching openclaw.plugin.json exists under the global extensions root

In that case, registry loading falls back to derived discovery, so Gateway validation sees the same newly added source-root plugin that plugin discovery can see.

Real behavior proof

  • Behavior addressed: a configured global source-root plugin added after the persisted registry was written no longer stays hidden from Gateway slot validation.
  • Real environment tested: Windows 11, Node v24.15.0, local OpenClaw source snapshot with the plugin registry test suite dependencies installed.
  • Exact command run after this patch:
node scripts/run-vitest.mjs src/plugins/plugin-registry-snapshot.test.ts --maxWorkers=1 --no-file-parallelism
  • Evidence after fix:
Test Files  1 passed (1)
Tests  20 passed | 1 skipped (21)
  • Observed result after fix: the new regression test writes a stale persisted index first, then creates state/extensions/memory-demo/openclaw.plugin.json, and loadPluginRegistrySnapshotWithMetadata returns source: derived with memory-demo present as a global plugin.
  • What was not tested: a live openclaw gateway startup using a real third-party memory plugin; the regression covers the exact persisted-registry decision point used by Gateway config validation.

Regression Test Plan

  • Added recovers configured global source plugins missing from a stale persisted registry in src/plugins/plugin-registry-snapshot.test.ts.
  • The existing persisted fast-path tests still cover keeping valid persisted registries and vanished install records unchanged.

Risk

The fallback is intentionally narrow. It does not rescan on every persisted registry load; it only invalidates when the config already references a missing plugin and the expected global source-root manifest exists.

@openclaw-barnacle openclaw-barnacle Bot added size: S triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. and removed triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. labels Jun 23, 2026
This was referenced Jun 23, 2026
Open
Closed
@clawsweeper

clawsweeper Bot commented Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed July 21, 2026, 1:31 AM ET / 05:31 UTC.

Summary
The branch adds a persisted-plugin-registry staleness check and regression test so configured global source plugins missing from the saved index fall back to derived discovery.

PR surface: Source +49, Tests +43. Total +92 across 2 files.

Reproducibility: no. live reproduction was run in this read-only review, but the current-main path is source-reproducible: a nonempty persisted index selects index-only manifest metadata, while a configured global manifest absent from that index is not otherwise recovered.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: serialized state: src/plugins/plugin-registry-snapshot.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #96046
Summary: This PR is a candidate fix for the open canonical report about persisted plugin-index metadata omitting a source-root plugin during Gateway validation.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Use manifest-based global discovery rather than the folder-name probe and add the arbitrary-directory-name regression case.
  • [P1] Add redacted real Gateway startup proof showing the configured source plugin validates after a persisted registry already exists.

Proof guidance:

  • [P1] Needs real behavior proof before merge: The PR body provides a focused regression-test result, but no real openclaw gateway startup with a source-root third-party plugin; add redacted runtime output after the repair. 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.

Risk before merge

  • [P1] Merging the directory-name probe leaves valid cloned source plugins undiscovered when their folder name differs from the manifest ID, so existing Gateway startup can still reject a configured plugin that normal discovery recognizes.

Maintainer options:

  1. Detect by manifest identity (recommended)
    Replace the folder-name existence probe with a narrow global-source discovery check that compares configured IDs to parsed manifest IDs, then add the mismatched-folder regression case.
  2. Accept the directory-name limitation
    Merge only if maintainers explicitly define source-root plugin directories as required to match manifest IDs, and document that compatibility constraint.

Next step before merge

  • [P2] A narrow mechanical repair can preserve the branch’s intended fallback while matching configured IDs against parsed global manifests instead of directory names.

Security
Cleared: The branch changes local registry selection only and introduces no dependency, secret, permission, download, or supply-chain surface.

Review findings

  • [P1] Match the manifest ID instead of the extension directory name — src/plugins/plugin-registry-snapshot.ts:560-564
Review details

Best possible solution:

Keep the persisted fast path, but when configured IDs are absent from it, use the existing narrow discovery/manifest parsing path to compare actual global manifest IDs; cover an arbitrary clone-directory name and show a redacted real Gateway startup after the fix.

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

No live reproduction was run in this read-only review, but the current-main path is source-reproducible: a nonempty persisted index selects index-only manifest metadata, while a configured global manifest absent from that index is not otherwise recovered.

Is this the best way to solve the issue?

No. The branch is a narrow and useful direction, but it checks a clone directory named after the configured ID instead of the manifest’s declared ID, so it does not cover the general discovery contract.

Full review comments:

  • [P1] Match the manifest ID instead of the extension directory name — src/plugins/plugin-registry-snapshot.ts:560-564
    The new check assumes the configured plugin ID is the directory name under the global extensions root. Discovery identifies plugins from their manifest metadata, so a valid clone such as extensions/custom-repo/openclaw.plugin.json declaring "id": "memory-demo" still keeps the persisted index and reproduces the Gateway rejection. Use parsed discovery candidates or the manifest registry to compare actual global plugin IDs, and add that layout to the regression test.
    Confidence: 0.94

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model internal, reasoning high; reviewed against d9ac878ea3ca.

Label changes

Label changes:

  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body provides a focused regression-test result, but no real openclaw gateway startup with a source-root third-party plugin; add redacted runtime output after the repair. 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.

Label justifications:

  • P1: A valid configured source plugin can still be rejected at Gateway startup even though discovery recognizes it.
  • merge-risk: 🚨 compatibility: The patch changes persisted-registry fallback behavior for existing plugin configurations, but its directory-name assumption leaves a supported layout incompatible with Gateway validation.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body provides a focused regression-test result, but no real openclaw gateway startup with a source-root third-party plugin; add redacted runtime output after the repair. 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

PR surface:

Source +49, Tests +43. Total +92 across 2 files.

View PR surface stats
Area Files Added Removed Net
Source 1 49 0 +49
Tests 1 43 0 +43
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 2 92 0 +92

Acceptance criteria:

  • [P1] node scripts/run-vitest.mjs src/plugins/plugin-registry-snapshot.test.ts --maxWorkers=1 --no-file-parallelism.
  • [P1] Run a redacted openclaw gateway startup with a pre-existing persisted registry and a configured global source plugin whose directory name differs from its manifest ID.

What I checked:

  • Current-main decision path: Current main loads a persisted registry snapshot and, when its index is nonempty, constructs Gateway-facing manifest metadata only from that installed index; a source-root plugin absent from the index is therefore omitted unless a staleness check forces derived discovery. (src/plugins/plugin-metadata-snapshot.ts, d9ac878ea3ca)
  • Current-main gap: The current persisted-registry staleness chain checks missing indexed files, configured load paths, stale metadata, and recovered managed installs, but has no global source-root check for a configured manifest ID absent from the index. (src/plugins/plugin-registry-snapshot.ts, d9ac878ea3ca)
  • Branch identity approximation: The new probe checks only <global extensions root>/<configured plugin id>/openclaw.plugin.json; it does not parse the manifest and compare its declared ID, so folder names and plugin IDs are incorrectly assumed to be identical. (src/plugins/plugin-registry-snapshot.ts:560, c676f0e5cd6d)
  • Manifest contract: The plugin guide shows the plugin ID as manifest metadata and separately describes source-checkout and package layout, so the supported identity is the manifest ID rather than a required clone-directory name. Public docs: docs/plugins/building-plugins.md. (docs/plugins/building-plugins.md:297, d9ac878ea3ca)
  • Related canonical report: The open report documents the same Gateway-versus-discovery inconsistency and remains the canonical user-facing issue; this PR is its candidate fix rather than a duplicate close target.

Likely related people:

  • zw-xysk: Authored two earlier proposals for the same persisted-index/source-root registry failure, providing the strongest available history signal for this exact decision surface. (role: recent area contributor; confidence: medium; commits: bae03b649c3f, 78d4755a0a82; files: src/plugins/plugin-registry-snapshot.ts, src/plugins/plugin-metadata-snapshot.ts)
  • harjothkhara: Worked on the closely related installed-index manifest reconstruction path for configured load-path plugins, which shares the registry-to-Gateway validation invariant. (role: adjacent contributor; confidence: low; commits: d8093a45135a; files: src/plugins/manifest-registry-installed.ts, src/plugins/plugin-metadata-snapshot.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

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 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.
Review history (1 earlier review cycle)
  • reviewed 2026-06-30T22:08:33.934Z sha d6d925a :: needs real behavior proof before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P1 High-priority user-facing bug, regression, or broken workflow. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jun 23, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jun 26, 2026
Closed
1 task
@harjothkhara harjothkhara mentioned this pull request Jul 2, 2026
Closed
@tangtaizong666
Merge remote-tracking branch 'upstream/main' into fix/global-source-p…
576e0d5 
…lugin-index-96046

# Conflicts:
#	src/plugins/plugin-registry-snapshot.test.ts
@tangtaizong666
Merge remote-tracking branch 'upstream/main' into fix/global-source-p…
f066432 
…lugin-index-96046
@clawsweeper clawsweeper Bot removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 7, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jul 21, 2026

Copy link
Copy Markdown

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jul 21, 2026
@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 22, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the stale Marked as stale due to inactivity label Jul 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P1 High-priority user-facing bug, regression, or broken workflow. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. size: S status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Gateway 'plugins.slots.memory: plugin not found' for an extensions/ plugin present in plugins list — 2026.6.9 regression

1 participant

@tangtaizong666