Summary

• repair stale root-level openclaw installs inside OpenClaw-managed npm plugin roots before updating npm-installed plugins
• prevent new Opik-style peer installs from materializing root node_modules/openclaw by running managed npm-root installs with --omit=peer
• trust legacy managed roots through the default npm root, the existing install record path, or an already-written managed-root marker; the marker is future proofing, not required for old installs
• narrow beta fallback so @beta only falls back to stable when the beta package/tag is missing, not when npm reports a real install failure like ERESOLVE

RCA

Externalized official plugins can live in ~/.openclaw/npm or another OpenClaw-managed npm root. Some legacy roots ended up with openclaw installed at the root of that managed npm project, either in root manifest fields, the package lock, or node_modules/openclaw.

The likely origination path is an external plugin that declared openclaw as a peer dependency. With modern npm, a peer dependency can be materialized during install unless we explicitly omit peers. That can create root-level node_modules/openclaw in the managed npm project even though OpenClaw already has an explicit host-peer symlink path for plugins.

That stale root package is poison for plugin updates. When a user moves from stable to beta, npm can resolve the plugin candidate correctly, then fail because the managed npm root still appears to contain an older openclaw package. In the bad box, this showed up as plugin beta update failure and fallback to the stable package, leaving Discord/WhatsApp/Codex-style externalized plugins behind even though the core OpenClaw package updated.

The old updater made that worse by treating every failed beta npm install as "beta unavailable" and falling back to the untagged/stable package. That is okay for a missing beta dist-tag. It is wrong for peer-resolution failures, malformed packages, or other real install errors.

Fix

The installer now prevents the normal peer path from creating root poison: managed npm-root plugin installs include --omit=peer as well as --omit=dev. OpenClaw then owns the openclaw peer through its existing host symlink, so plugin packages can still declare peerDependencies.openclaw without npm installing a second OpenClaw copy into the managed root.

The install path is still intentionally non-blocking. We do not reject plugins that declare openclaw. If an installed package declares openclaw in peer, direct, or optional dependencies, the installed package gets linked to the host OpenClaw package before dependency-tree scanning when it came from the managed npm root. That avoids stranding users with a blocked install just because npm or a package manifest tried to materialize OpenClaw locally.

The installer also inspects the managed npm root before and after installing any non-openclaw npm plugin. If it finds stale root-level openclaw state, it first uses native npm cleanup commands from the managed root: npm uninstall openclaw and npm prune. Only if native cleanup leaves poison behind does it fall back to directly removing the root manifest/lock entries and quarantining stale filesystem payloads.

The repair is conservative. It refuses bare OpenClaw installs, roots overlapping the running OpenClaw package, and pnpm workspaces. It also refuses unknown custom roots unless the root is the default managed npm dir, came from an existing npm install record, or already has the managed-root marker. That keeps the repair from mutating a user's unrelated npm project while still fixing old OpenClaw-managed plugin roots retroactively.

Update now derives the original npm root from each npm install record and passes that root back into install/update. That means users who installed official externalized plugins into a non-default OpenClaw-managed root do not get silently redirected to the default root during update.

Beta fallback is now limited to missing-package/missing-tag cases (npm_package_not_found, ETARGET, notarget, missing dist-tag/tag text). Real beta install failures now surface as errors so we do not mask broken state by downgrading the plugin.

Coverage

Happy paths covered:

• unchanged managed npm root when no stale root openclaw exists
• normal plugin dependency upsert still preserves other managed plugin dependencies
• managed npm-root installs use --omit=peer, so peer dependencies do not materialize root openclaw
• native npm cleanup repairs stale root openclaw while preserving plugin packages
• npm updates reuse the npm root derived from an existing install record
• beta update falls back to stable only when the beta tag/package is unavailable

Non-happy paths covered:

• stale root openclaw in dependencies, optionalDependencies, peerDependencies, root lock metadata, lock-only state, and filesystem-only state
• Opik-style peer install where npm materializes root openclaw: post-install repair removes the root poison and links the plugin to the host OpenClaw package
• required-peer npm e2e install where npm would otherwise create a root OpenClaw package in the managed plugin root
• corrupt package lock gets quarantined during fallback repair
• plugin-local nested node_modules/openclaw is not treated as root poison
• bare openclaw npm roots and pnpm workspaces are skipped instead of mutated
• unproven custom roots are skipped; legacy install-record roots are trusted and repaired
• invalid beta package installs do not fall back to stable
• beta ERESOLVE peer-resolution failures do not fall back to stable

Verification

• pnpm exec oxfmt --check --threads=1 src/infra/safe-package-install.ts src/infra/safe-package-install.test.ts src/plugins/install.ts src/plugins/install.npm-spec.test.ts
• pnpm exec oxlint --threads=1 src/infra/safe-package-install.ts src/infra/safe-package-install.test.ts src/plugins/install.ts src/plugins/install.npm-spec.test.ts
• git diff --check
• Testbox tbx_01kqxy0ntk8s446ynqa06a53re: pnpm test:serial src/infra/safe-package-install.test.ts src/infra/npm-managed-root.test.ts src/plugins/install.npm-spec.test.ts src/plugins/install.npm-spec.e2e.test.ts src/plugins/update.test.ts (117 tests)
• Testbox tbx_01kqxy0ntk8s446ynqa06a53re: pnpm check:changed (lanes: core, coreTests, docs)