Summary

• Problem: plugin npm installs can encounter a root-managed setup where .openclaw/npm/node_modules/openclaw is the active OpenClaw runtime, not disposable plugin peer debris.
• Why it matters: the stale peer cleanup path could uninstall or scrub that active runtime while installing another plugin, which can leave gateway startup importing missing runtime files.
• What changed: repairManagedNpmRootOpenClawPeer now detects when the managed-root node_modules/openclaw realpath matches the active host package root and skips cleanup in that case.
• What did NOT change (scope boundary): stale/transient openclaw peer cleanup still runs when node_modules/openclaw is not the active host runtime.
• AI-assisted: yes; I understand the changed guard and verified it with focused tests plus real filesystem proof below.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra
• Plugins / install runtime

Linked Issue/PR

• Related: Remove OpenClaw from runtime dependencies xDarkicex/openclaw-memory-libravdb#179
• This PR fixes a bug or regression

Real behavior proof

• Behavior addressed: root-managed plugin installs preserve the active openclaw runtime package instead of treating it as stale peer debris.
• Real environment tested: macOS local OpenClaw checkout on branch codex/preserve-host-runtime-plugin-installs, Node via repo toolchain, temporary real managed npm root under /var/folders/.../T, no mocks and no test runner.
• Exact steps or command run after this patch: ran a node --import tsx --input-type=module script that created a real managed npm root with package.json, package-lock.json, node_modules/openclaw, .bin/openclaw, and dist/cli/gateway-lifecycle.runtime.js, then called the patched repairManagedNpmRootOpenClawPeer against that active host package.
• Evidence after fix: Terminal transcript from the real filesystem reproduction:

$ node --import tsx --input-type=module <real-filesystem-proof-script>
script_created_managed_root_with=openclaw package, package-lock, CLI shim, gateway lifecycle runtime file
script_invoked=repairManagedNpmRootOpenClawPeer({ npmRoot, packageRoot: hostRoot })
fixture=/var/folders/04/4nmxfbmn44d21bwf7cqknhgc0000gn/T/openclaw-real-proof-12GcMB
repair_result=false
manifest_openclaw_dependency=2026.5.12-beta.6
lock_openclaw_package_version=2026.5.12-beta.6
host_package_version=2026.5.12-beta.6
bin_still_exists=true
gateway_lifecycle_runtime_still_exists=true

• Observed result after fix: the repair function returned false, did not invoke npm uninstall/prune, and the active host package, lockfile entry, CLI shim, and gateway lifecycle runtime file remained present.
• What was not tested: no live Telegram/Discord gateway restart in this proof; the proof isolates the root-managed runtime mutation that caused the gateway startup failure.
• Before evidence (optional but encouraged): local incident logs from the affected setup showed gateway startup failing with ERR_MODULE_NOT_FOUND for /Users/jason/.openclaw/npm/node_modules/openclaw/dist/cli/gateway-lifecycle.runtime.js after plugin install activity mutated the same managed npm root.

Root Cause (if applicable)

• Root cause: the managed npm root is used both for installed plugin packages and, in root-managed installs, for the active openclaw package. The stale peer cleanup path assumed any root-level node_modules/openclaw was plugin peer debris.
• Missing detection / guardrail: cleanup did not compare the root-level node_modules/openclaw realpath with the active OpenClaw package root before uninstalling or scrubbing it.
• Contributing context (if known): a plugin with a runtime dependencies.openclaw entry can cause npm to materialize or mutate root-level openclaw state during plugin install.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/infra/npm-managed-root.test.ts and src/plugins/install.npm-spec.test.ts.
• Scenario the test should lock in: active root-managed host package is preserved, while stale non-host openclaw peer packages are still cleaned up.
• Why this is the smallest reliable guardrail: the bug lives at the managed npm root repair/install seam; these tests exercise that seam without requiring live channel credentials.
• Existing test that already covers this (if any): existing stale peer cleanup tests covered removal, but not active-host preservation.

User-visible / Behavior Changes

OpenClaw plugin installs are less likely to break the currently running root-managed OpenClaw runtime when a plugin dependency graph references openclaw.

Diagram (if applicable)

Before:
plugin install -> stale peer cleanup sees node_modules/openclaw -> uninstall/scrub -> active runtime files can disappear

After:
plugin install -> cleanup realpath-checks active host -> preserve active runtime -> continue plugin install

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local development machine
• Runtime/container: Node repo toolchain, pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): plugin install runtime; no live channel credentials used
• Relevant config (redacted): temporary managed npm root fixture with openclaw@2026.5.12-beta.6 and @xdarkicex/openclaw-memory-libravdb@1.4.69

Steps

1. Created a temporary root-managed npm layout where node_modules/openclaw is the active host package.
2. Ran the patched managed-root repair function against that layout and asserted npm cleanup was not invoked.
3. Ran focused formatter and behavior tests for the changed files.

Expected

• Active host node_modules/openclaw remains installed.
• Stale peer cleanup is skipped only for the active host package.
• Existing stale peer cleanup behavior remains covered by tests.

Actual

• Real proof output showed repair_result=false, bin_still_exists=true, and gateway_lifecycle_runtime_still_exists=true.
• pnpm exec oxfmt --check --threads=1 src/infra/npm-managed-root.ts src/infra/npm-managed-root.test.ts src/plugins/install.npm-spec.test.ts passed.
• OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/test-projects.mjs src/infra/npm-managed-root.test.ts src/plugins/install.npm-spec.test.ts passed with 12 infra tests and 33 plugin tests.

Verification

• pnpm exec oxfmt --check --threads=1 src/infra/npm-managed-root.ts src/infra/npm-managed-root.test.ts src/plugins/install.npm-spec.test.ts
• OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/test-projects.mjs src/infra/npm-managed-root.test.ts src/plugins/install.npm-spec.test.ts
• Real filesystem reproduction shown in the Real behavior proof section above.