fix(doctor): repair managed plugin openclaw peer links by TheCrazyLex · Pull Request #77412 · openclaw/openclaw

TheCrazyLex · 2026-05-04T16:50:15Z

"## Summary\n- Repair missing or stale host openclaw peer links for managed npm plugins that declare peerDependencies.openclaw.\n- Warn in read-only doctor mode, and relink <plugin>/node_modules/openclaw during openclaw doctor --fix before missing-plugin install repair runs.\n- Document the repair path and add changelog coverage for the openclaw/plugin-sdk/* import failure.\n\n## Verification\n- corepack pnpm exec oxfmt --check --threads=1 CHANGELOG.md docs/cli/doctor.md docs/cli/plugins.md docs/gateway/doctor.md src/commands/doctor-plugin-registry.ts src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.ts src/commands/doctor/repair-sequencing.test.ts\n- git diff --check\n- corepack pnpm test src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.test.ts\n- codex review --base origin/main\n- corepack pnpm changed:lanes --json selected the core, coreTests, and docs lanes; I did not run the broad changed gate locally because this machine does not have Blacksmith/Testbox available and the repository guidance routes broad changed gates through Testbox.\n\ncorepack pnpm install completed successfully before validation. It logged an optional @discordjs/opus native build fallback failure on this ARM/Node 25 environment, but pnpm exited 0 and the targeted checks above passed.\n\n## AI-assisted\n- AI-assisted: yes, prepared with Codex.\n- Testing: targeted local tests, formatting, diff whitespace checks, lane selection, and Codex review completed.\n- I understand the change: doctor now restores the host openclaw peer link that package-local managed npm plugin runtimes need for openclaw/plugin-sdk/* imports, without running npm or modifying unrelated dependencies.\n"

Real behavior proof

Behavior or issue addressed: Managed npm plugins that declare peerDependencies.openclaw but are missing <plugin>/node_modules/openclaw are now reported by read-only openclaw doctor, and openclaw doctor --fix relinks them.
Real environment tested: Local OpenClaw checkout on macOS, isolated OPENCLAW_STATE_DIR=/tmp/openclaw-peer-proof.Aujcax/state, OpenClaw CLI 2026.5.12-beta.1 (974f3df).
Exact steps or command run after this patch: Created an isolated managed npm plugin package with peerDependencies.openclaw and no node_modules/openclaw, then ran pnpm openclaw doctor --non-interactive, pnpm openclaw doctor --non-interactive --fix, and inspected the resulting link with Node fs.lstatSync/fs.realpathSync.
Evidence after fix: Terminal capture from the real CLI run:

READ_ONLY_DOCTOR
◇  Plugin registry ────────────────────────────────────────────────────────────╮
│  Managed npm OpenClaw host peer links need repair:                           │
│  - codex-plugin: missing                                                     │
│    /tmp/openclaw-peer-proof.Aujcax/state/npm/node_modules/codex-plugin/node  │
│  Repair with openclaw doctor --fix to relink managed npm plugin              │
FIX_DOCTOR
◇  Plugin registry ──────────────────────────────────────────────╮
│  Repaired OpenClaw host peer link(s) for 1 managed npm plugin  │
LINK_RESULT
{"isSymlink":true,"target":true}

Observed result after fix: Read-only doctor printed the managed npm peer-link repair warning and openclaw doctor --fix created a symlink whose realpath resolves back to the OpenClaw checkout.
What was not tested: Production gateway startup was not exercised; this change is limited to CLI doctor/install/update repair of the plugin-local peer link.

clawsweeper · 2026-05-04T16:53:44Z

Codex review: needs real behavior proof before merge.

Summary
The PR adds doctor audit/repair for managed npm plugin node_modules/openclaw peer links, docs/changelog notes, and tests around peer-link relinking and skipped repairs.

Reproducibility: yes. by source inspection. Current main lacks the doctor peer-link audit/repair path, and the PR head still has a concrete read-only audit false-negative when resolveOpenClawPackageRootSync returns null.

Real behavior proof
Needs real behavior proof before merge: The PR body has tests and checks, but no after-fix real doctor repair output, logs, screenshot, recording, or linked artifact from a real setup. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, ask a maintainer to comment @clawsweeper re-review.

Next step before merge
Needs contributor or maintainer update for the host-root audit false-negative plus real behavior proof; automation should not be queued while contributor setup proof is missing.

Security
Cleared: No concrete security or supply-chain regression was found; the symlink repair path stays local and rejects non-directory or symlinked package-local node_modules parents.

Review findings

[P2] Report host-root audit failures — src/plugins/plugin-peer-link.ts:303-304

Review details

Best possible solution:

Keep the doctor-owned repair boundary, make read-only doctor report host-root resolution failures, and require real openclaw doctor --fix proof before merge.

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

Yes, by source inspection. Current main lacks the doctor peer-link audit/repair path, and the PR head still has a concrete read-only audit false-negative when resolveOpenClawPackageRootSync returns null.

Is this the best way to solve the issue?

Not yet. Doctor is the right repair boundary for managed npm peer-link drift, but the PR should report host-root audit failures and include real behavior proof before it is the best merge candidate.

Full review comments:

[P2] Report host-root audit failures — src/plugins/plugin-peer-link.ts:303-304
When read-only doctor audit cannot resolve the host OpenClaw package root, this returns an empty clean result. That leaves normal openclaw doctor silent even though peer-dependent managed plugins cannot be checked against the host package, so emit an audit issue/note instead of reporting no broken links.
Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.86

Acceptance criteria:

corepack pnpm test src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.test.ts src/plugins/plugin-peer-link.test.ts src/plugins/install.npm-spec.test.ts src/plugins/install.test.ts src/plugins/update.test.ts
corepack pnpm exec oxfmt --check --threads=1 CHANGELOG.md docs/cli/doctor.md docs/cli/plugins.md docs/gateway/doctor.md src/commands/doctor-plugin-registry.ts src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.ts src/commands/doctor/repair-sequencing.test.ts src/plugins/plugin-peer-link.ts src/plugins/plugin-peer-link.test.ts src/plugins/install.ts src/plugins/install.test.ts src/plugins/install.npm-spec.test.ts src/plugins/update.ts src/plugins/update.test.ts
git diff --check
redacted real openclaw doctor --fix output or logs showing managed npm peer-link repair

What I checked:

Current main lacks doctor peer-link audit: On current main, maybeRepairPluginRegistryState handles stale bundled-plugin shadows and then returns in read-only mode; there is no managed npm openclaw peer-link audit or repair call in the doctor registry path. (src/commands/doctor-plugin-registry.ts:265, f863447fe165)
Current main repair sequencing lacks peer-link repair: Current main's doctor repair sequence runs stale managed bundled-plugin cleanup before Codex route and missing-install repairs, but does not run a managed npm OpenClaw peer-link repair step. (src/commands/doctor/repair-sequencing.ts:72, f863447fe165)
Current main has only install/update peer relinking overlap: The existing helper relinks managed npm packages that declare peerDependencies.openclaw, but it is an install/update helper and not a read-only doctor diagnostic path. (src/plugins/plugin-peer-link.ts:123, f863447fe165)
Related merged peer-link provenance: The related merged work fix(plugins): repair managed npm openclaw peers is on main and explains the install/update peer-link repair overlap that this PR builds on, but it does not make the doctor-specific change obsolete. (src/plugins/plugin-peer-link.ts:85, 8e533490ab0a)
PR head adds doctor repair and read-only warning coverage: The PR head adds maybeRepairManagedNpmOpenClawPeerLinks and tests for both shouldRepair: true repair and shouldRepair: false warning behavior. (src/commands/doctor-plugin-registry.test.ts:512, 974f3df7eb0f)
Remaining PR head audit false-negative: The PR head's read-only audit returns an empty clean result when the host OpenClaw package root cannot be resolved, leaving openclaw doctor silent in that diagnostic failure mode. (src/plugins/plugin-peer-link.ts:303, 974f3df7eb0f)

Likely related people:

@steipete: Peter Steinberger authored the related merged managed npm peer-link repair on main and the current main head also recently touched adjacent plugin/doctor surfaces; the current PR branch commits are also under this name in the provided PR context. (role: recent area contributor; confidence: high; commits: 8e533490ab0a, f863447fe165; files: src/plugins/plugin-peer-link.ts, src/plugins/install.ts, src/plugins/update.ts)

Remaining risk / open question:

The PR still lacks real after-fix doctor output from a packaged or otherwise real managed npm plugin setup.
The remaining host-root audit path was verified by source inspection, not by an executed runtime reproduction in this read-only review.

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

Re-review progress:

State: Review in progress
Detail: Targeted re-review run started; Codex is reviewing the item.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25718308577
Updated: 2026-05-12T06:47:50.652Z

Copilot

Pull request overview

This PR extends doctor’s managed-plugin repair flow so OpenClaw can restore missing/stale package-local openclaw peer links for managed npm plugins, which helps plugin SDK imports keep resolving after npm drift or updates.

Changes:

Added managed npm peer-link detection/repair for plugins that declare peerDependencies.openclaw.
Ran that repair before missing configured plugin install repair in the doctor fix sequence.
Documented the behavior in CLI/gateway docs and added a changelog entry.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/commands/doctor/repair-sequencing.ts`	Inserts peer-link repair into the doctor fix order before missing-plugin installs.
`src/commands/doctor/repair-sequencing.test.ts`	Updates sequencing tests to cover the new repair step ordering.
`src/commands/doctor-plugin-registry.ts`	Adds detection, warning, repair, and refresh hooks for managed npm `openclaw` peer links.
`src/commands/doctor-plugin-registry.test.ts`	Adds tests for missing/stale peer-link warning and repair behavior.
`docs/gateway/doctor.md`	Documents peer-link repair in gateway doctor docs.
`docs/cli/plugins.md`	Documents peer-link repair in plugin registry docs.
`docs/cli/doctor.md`	Updates doctor CLI notes to mention peer-link relinking.
`CHANGELOG.md`	Adds release note for the new doctor/plugin repair behavior.

+    cwd: process.cwd(),
+  });
+  if (!hostRoot) {
+    return [];


+        "Managed npm plugin packages are missing their OpenClaw host peer link:",
+        ...missingOrStaleLinks.map((link) => `- ${link.packageName}`),
+        `Repair with ${formatCliCommand("openclaw doctor --fix")} to relink the host openclaw package for plugin SDK imports.`,


+        "Repaired OpenClaw host peer link(s) for managed npm plugins:",
+        ...repaired.map((link) => `- ${link.packageName}`),


TheCrazyLex · 2026-05-04T17:07:33Z

Updated this PR after the review comments.

Addressed:

ClawSweeper path-boundary finding: managed npm dependency keys are now checked against the managed node_modules root before inspection, and existing package directories must realpath back inside that root before any repair candidate is created. Added a regression test with a corrupted ../../outside-plugin dependency key to verify doctor --fix does not create an escaped node_modules/openclaw link.
Copilot host-root false-negative: if doctor cannot resolve the host OpenClaw package root, it now emits a registry note instead of silently returning no repair candidates.
Copilot package-name readability comments: doctor output now includes pluginId: packageName when the manifest id differs from the npm package name.

Re-ran after rebasing onto current origin/main:

corepack pnpm exec oxfmt --check --threads=1 CHANGELOG.md docs/cli/doctor.md docs/cli/plugins.md docs/gateway/doctor.md src/commands/doctor-plugin-registry.ts src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.ts src/commands/doctor/repair-sequencing.test.ts
git diff --check origin/main...HEAD
corepack pnpm test src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.test.ts

steipete · 2026-05-12T06:48:56Z

Landing proof for PR 77412:

Local focused tests: pnpm test src/plugins/plugin-peer-link.test.ts src/plugins/install.test.ts src/plugins/install.npm-spec.test.ts src/plugins/update.test.ts src/commands/doctor-plugin-registry.test.ts src/commands/doctor/repair-sequencing.test.ts -- --reporter=verbose
Local formatting/whitespace: pnpm exec oxfmt --check --threads=1 ..., git diff --check
Crabbox/Testbox: tbx_01krde1jx199rnpm2rv1rdcj76, focused tests + pnpm check:changed, exit 0
GitHub Actions: required check suite green; Real behavior proof rerun passed after adding the real CLI doctor output to the PR body
Real CLI proof: isolated OPENCLAW_STATE_DIR with a managed npm plugin missing node_modules/openclaw; read-only openclaw doctor reported the repair hint, and openclaw doctor --fix created the symlink ({"isSymlink":true,"target":true})

Known gap: production gateway startup was not exercised; the changed behavior is limited to CLI doctor/install/update repair of plugin-local peer links.

Thanks @TheCrazyLex.

steipete · 2026-05-12T06:49:46Z

Landed on main.

Source PR head: 974f3df7eb0f853949f014c1f797ea604263523c
Squash merge commit: a290cd6
Gate: GitHub Actions green after the real-behavior proof update; Crabbox/Testbox tbx_01krde1jx199rnpm2rv1rdcj76 ran focused tests plus pnpm check:changed, exit 0.
Real proof: isolated CLI openclaw doctor warned for the missing managed npm peer link; openclaw doctor --fix relinked it and lstat confirmed {"isSymlink":true,"target":true}.

Thanks @TheCrazyLex.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25718308577
Updated: 2026-05-12T06:52:40.490Z

Copilot AI review requested due to automatic review settings May 4, 2026 16:50

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime commands Command implementations size: M labels May 4, 2026

Copilot started reviewing on behalf of TheCrazyLex May 4, 2026 16:50 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

TheCrazyLex force-pushed the fix/doctor-managed-openclaw-peer-links branch from aad9b4b to bd43607 Compare May 4, 2026 17:07

clawsweeper Bot mentioned this pull request May 6, 2026

[Bug]: @openclaw/codex fails before reply when local npm tree loses openclaw peer link #78185

Closed

steipete mentioned this pull request May 6, 2026

fix(plugins): repair managed npm openclaw peers #78291

Merged

clawsweeper Bot mentioned this pull request May 10, 2026

npm plugin peer link drift can leave Discord tokens configured_unavailable #80205

Closed

fix(doctor): repair managed plugin peer links

cd02893

steipete force-pushed the fix/doctor-managed-openclaw-peer-links branch from bd43607 to cd02893 Compare May 12, 2026 05:57

openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 12, 2026

steipete added 3 commits May 12, 2026 07:06

fix(plugins): reject skipped peer-link installs

4a39103

fix(plugins): ignore unrelated peer-link skips

5f541d7

fix(doctor): preview broken managed peer links

974f3df

openclaw-barnacle Bot added size: L proof: supplied External PR includes structured after-fix real behavior proof. and removed size: M triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 12, 2026

steipete merged commit a290cd6 into openclaw:main May 12, 2026
120 of 128 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(doctor): repair managed plugin openclaw peer links#77412

fix(doctor): repair managed plugin openclaw peer links#77412
steipete merged 4 commits into
openclaw:mainfrom
TheCrazyLex:fix/doctor-managed-openclaw-peer-links

TheCrazyLex commented May 4, 2026 •

edited by steipete

Loading

Uh oh!

clawsweeper Bot commented May 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

TheCrazyLex commented May 4, 2026

Uh oh!

steipete commented May 12, 2026

Uh oh!

Uh oh!

steipete commented May 12, 2026 •

edited by clawsweeper Bot

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		"Repaired OpenClaw host peer link(s) for managed npm plugins:",
		...repaired.map((link) => `- ${link.packageName}`),

Uh oh!

Conversation

TheCrazyLex commented May 4, 2026 • edited by steipete Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Real behavior proof

Uh oh!

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

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

TheCrazyLex commented May 4, 2026

Uh oh!

steipete commented May 12, 2026

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

TheCrazyLex commented May 4, 2026 •

edited by steipete

Loading

clawsweeper Bot commented May 4, 2026 •

edited

Loading

steipete commented May 12, 2026 •

edited by clawsweeper Bot

Loading