Closes #101049

What Problem This Solves

Fixes an issue where installing a channel plugin through the managed npm flow could report success with an empty or incomplete dependency tree. The plugin then appeared installed and loaded at startup, but its provider failed when importing a missing runtime dependency. In the reported Microsoft Teams case, webhook deliveries failed while the local install still looked healthy, and only a manual npm reinstall inside the managed project restored the channel.

Why This Change Was Made

The managed npm install path verified lockfile metadata, platform packages, and peer links after npm install, but it did not verify that the installed plugin's own declared runtime dependencies resolved from the installed package root. Doctor likewise did not classify an installed-but-hollow dependency tree as repairable, even though plugin status already exposed the dependency state.

This change reuses the existing plugin dependency-status machinery in both paths:

• Managed npm installs now reject a package when a required declared dependency is absent after npm exits successfully. The error names the missing packages and uses the existing managed-root rollback path.
• A dependency counts as materialized only when its package root contains the package.json npm places in published packages, so an empty residual directory is not mistaken for an installed dependency.
• Doctor checks active source:npm plugin roots that canonically match their persisted install record, names missing packages in core/doctor/configured-plugin-installs, and sends affected installs through the retention-marker-backed package updater. This includes catalog-backed official installs, so same-version repairs activate a fresh generation instead of reusing the hollow tree.
• Dependency normalization follows npm semantics where optionalDependencies override same-name dependencies, so packages that intentionally make a dependency optional are not rejected when npm legitimately omits it.

Missing optional dependencies do not fail either path. Resolution follows Node walk-up semantics, so a required dependency hoisted to the managed project root remains valid. Import probing at every gateway startup is outside this change; the install path covers new writes and doctor covers persisted corruption.

User Impact

A managed plugin install with a hollow dependency tree now fails loudly instead of leaving a plugin that appears healthy but cannot run. Existing corrupted npm installs are reported by doctor with the missing package names, and doctor --fix reinstalls the package into a healthy generation instead of requiring manual npm commands in an internal managed directory. Packages that list the same package in both dependencies and optionalDependencies keep npm's override behavior and remain installable when that dependency is absent.

Evidence

Full E2E: partial. The persisted-corruption detection and repair path is direct CLI E2E. The install-time hollow-tree fault remains a production-function integration test because real npm cannot be made to deterministically exit successfully while omitting a required dependency.

Atomic proof status

• Reject hollow install --- production-function integration: the regression calls the production npm installer; only the npm subprocess/materialization result is fault-injected. It is RED on the base behavior (ok: true) and GREEN here with the missing package named.
• Rollback failed managed root --- production-function integration + direct filesystem after-state: the same regression verifies that the failed plugin package root no longer exists after rejection.
• Preserve npm optional override semantics --- production-function integration + real npm contract check: a regression installs a package declaring the same absent package as both required and optional, and the production installer accepts it. A direct npm check also confirmed that optionalDependencies can override same-name dependencies and that npm may exit successfully while omitting the package.
• Detect a corrupted installed tree --- direct E2E: a real CLI install was corrupted by removing its plugin-local ms, after which focused doctor returned one finding naming ms.
• Repair the corrupted installed tree --- direct E2E: from an already-corrupt managed generation, real doctor --fix fetched npm metadata and the package tarball, switched the install record to a fresh activation generation, restored [email protected], and left focused doctor clean.
• Retain official same-version repairs --- production-function regression: the official catalog path was RED because it bypassed the retained updater; it now routes through the marker-backed updater and verifies a fresh repair generation.
• Preserve detection across official-package mismatch --- production-function regression: an active npm record whose configured id also mapped to a different official package was RED with no configured-install finding; detection now stays on the record-backed route and names the missing dependency.
• Fail closed when retention cannot be prepared --- production-function regression: a real marker-directory filesystem failure was RED because doctor still invoked the updater; the affected dependency repair is now warned and skipped before any package update.
• Report skipped dependency repairs --- production-function regression: a valid npm record without spec was RED because doctor cleared its marker but emitted no warning or failed id; mixed-batch coverage now reports that failure while an unrelated repair completes and keeps its retained marker.
• Reject empty dependency directories --- production-function regression: a real Node resolution probe returns MODULE_NOT_FOUND for the residual directory; install and doctor/status regressions now require the dependency package manifest.
• Healthy npm installs --- direct real-npm non-regression: real managed npm installs with complete nested dependency trees passed the new gate.

Real behavior proof

• Behavior or issue addressed: installed npm plugins whose required dependency tree is missing or later becomes corrupted, while preserving npm-valid optional dependency overrides.
• Real environment tested: Linux source checkout, Node v22.22.1, isolated OPENCLAW_STATE_DIR, and a localhost-only npm registry serving real metadata and a tarball for [email protected] with bundled [email protected].
• Exact steps or command run after this patch: start from a genuine source:npm install record whose active path is already a managed generation; move its plugin-local node_modules/ms aside; run focused doctor lint; run doctor --fix --yes --non-interactive --no-workspace-suggestions with npm pointed at the fresh local registry; independently read the updated SQLite record and resolve the restored dependency; rerun focused doctor lint.
• Evidence after fix: copied terminal/registry/database output from the isolated run, with the state path shortened to $STATE_DIR:

$ openclaw doctor --lint --json --only core/doctor/configured-plugin-installs
{"ok":false,"checksRun":1,"checksSkipped":50,"findings":[{"checkId":"core/doctor/configured-plugin-installs","severity":"warning","message":"Configured plugin dep-proof-demo is installed but required dependencies are missing from its dependency tree: ms.","target":"dep-proof-demo",...}]}

$ openclaw doctor --fix --yes --non-interactive --no-workspace-suggestions
Repaired broken installed plugin "dep-proof-demo".

# Fresh-cache registry requests during doctor repair
GET /dep-proof-demo                                      200
GET /dep-proof-demo/-/dep-proof-demo-1.0.0.tgz          200

# Independent read of installed_plugin_index after repair
source: npm
spec: [email protected]
integrity/shasum: present
installPath: $STATE_DIR/npm/projects/dep-proof-demo__openclaw-generation__g-2e66e24c4f3583e3/node_modules/dep-proof-demo

# Independent package read from the active generation
ms 2.1.3

$ openclaw doctor --lint --json --only core/doctor/configured-plugin-installs
{"ok":true,"checksRun":1,"checksSkipped":50,"findings":[]}

• Observed result after fix: doctor identified the deliberately removed required package, the repair used the real npm updater and generation swap, the active tree resolved the exact restored package version, and the same focused check became clean.
• What was not tested: a live Microsoft Teams webhook round-trip, because the changed boundary is plugin installation/repair rather than Bot Framework delivery. A naturally hollow successful npm run was not reproduced; install rejection therefore remains mock-fault integration proof and the aggregate proof classification remains partial rather than full E2E.

Current main merge refresh

The branch carries two signed merge commits after the reviewed head. Merge 704e5a2fbfd35ceefb79664f88a4d77c783b07ba refreshed the then-current main 4ae4b5c2a464608045e29fe72793dbb6fbbcdad7 with the reviewed six-file patch byte-identical. Merge d5ebd2c9faf5e19d4b7a48ec102e46c59a1ae211 resolves conflicts against current main 9497450511d2996dae6632305ee2111a93377657, where the plugin install split (#107960) moved the managed npm install flow out of src/plugins/install.ts into focused modules. The install-time dependency gate now sits at the same anchor inside installPluginFromManagedNpmRoot in src/plugins/install-managed-npm.ts; the ported import and gate lines are byte-identical to the reviewed change, src/plugins/install.ts is byte-identical to main's re-export barrel and leaves the diff, and the other five changed files carry the reviewed change merged with current main.

The exact merged head passed the direct affected suites and repository changed-file gate:

src/plugins/install.npm-spec.test.ts                                  65 passed
src/commands/doctor/shared/missing-configured-plugin-install.test.ts  95 passed
src/plugins/status.registry-snapshot.test.ts                            5 passed
check:changed --base 9497450511d2996dae6632305ee2111a93377657        core + coreTests passed
oxfmt changed files                                                    clean
oxlint changed files                                                   clean

check:changed included core production/test typechecks, conflict-marker and dependency guards, changed-file lint, database-first/media/runtime-sidecar guards, and runtime import-cycle checks. One lane is excluded: the max-lines ratchet fails via a stale main baseline entry for src/agents/modes/interactive/theme/theme.ts (file and baseline byte-identical to main here); all other lanes passed with that entry pruned locally. Hosted checks for this new head are pending and should be judged from this head's check runs.

Scope, compatibility, and risk

No dependency, lockfile, configuration schema, authentication, permissions, network access, or persisted-record schema changes are introduced. The behavior change is limited to rejecting required dependencies that do not resolve after a managed npm install, preserving npm's optional override semantics during dependency status normalization, and treating the same persisted missing-required condition as a repairable doctor finding for the active matching npm install record. Path/archive records and same-id configured shadows are not advertised as auto-repairable. Optional dependencies, same-name optional overrides, and valid hoisted dependencies have explicit non-regression coverage. The main risks are false attribution and reusing an already-hollow same-version project; canonical root/source eligibility tests, fresh-generation retention tests, real nested-dependency installs, optional-override coverage, and direct repeated-generation repair E2E cover those boundaries.

AI-assisted; contributor manually reviewed and is responsible for the change.