vilvona 1.0.0

package/docs/plugins/copilot.md

@@ -0,0 +1,355 @@
+---
+summary: "Run OpenClaw embedded agent turns through the external GitHub Copilot SDK harness"
+title: "Copilot SDK harness"
+read_when:
+  - You want to use the GitHub Copilot SDK harness for an agent
+  - You need configuration examples for the `copilot` runtime
+  - You are wiring an agent to subscription Copilot (github / openclaw / copilot) and want it to run through the Copilot CLI
+---
+
+The external `@openclaw/copilot` plugin lets OpenClaw run embedded subscription
+Copilot agent turns through the GitHub Copilot CLI (`@github/copilot-sdk`)
+instead of the built-in PI harness.
+
+Use the Copilot SDK harness when you want the Copilot CLI session to own the
+low-level agent loop: native tool execution, native compaction
+(`infiniteSessions`), and CLI-managed thread state under `copilotHome`.
+OpenClaw still owns chat channels, session files, model selection, OpenClaw
+dynamic tools (bridged), approvals, media delivery, the visible transcript
+mirror, `/btw` side questions (handled by the in-tree PI fallback — see
+[Side questions (`/btw`)](#side-questions-btw)), and `openclaw doctor`.
+
+For the broader model/provider/runtime split, start with
+[Agent runtimes](/concepts/agent-runtimes).
+
+## Requirements
+
+- OpenClaw with the `@openclaw/copilot` plugin installed.
+- If your config uses `plugins.allow`, include `copilot` (the manifest
+  id declared by the plugin). A restrictive
+  allowlist that uses the npm-style `@openclaw/copilot` package name
+  will leave the plugin blocked and the runtime will not load
+  even with `agentRuntime.id: "copilot"`.
+- A GitHub Copilot subscription that can drive the Copilot CLI (or a
+  `gitHubToken` env / auth-profile entry for headless / cron runs).
+- A writable `copilotHome` directory. The harness defaults to
+  `~/.openclaw/agents/<agentId>/copilot` for full per-agent isolation. The
+  platform default (`%APPDATA%\copilot` on Windows, `$XDG_CONFIG_HOME/copilot`
+  or `~/.config/copilot` elsewhere) is used as the doctor probe fallback when
+  no explicit home is set.
+
+`openclaw doctor` runs the plugin
+[doctor contract](#doctor-and-probes) for the extension; failures there are
+the canonical way to confirm the environment is ready before opting an agent
+in.
+
+## Plugin install
+
+The Copilot runtime is an external plugin so the core `openclaw` package does
+not carry the `@github/copilot-sdk` dependency or its platform-specific
+`@github/copilot-<platform>-<arch>` CLI binary. Together they add roughly
+260 MB, so install them only for agents that opt into this runtime:
+
+```bash
+openclaw plugins install @openclaw/copilot
+```
+
+The wizard installs the plugin the first time you select a
+`github-copilot/*` model **and** your config opts the model (or its
+provider) into the Copilot agent runtime via
+`agentRuntime: { id: "copilot" }` (see [Quickstart](#quickstart) below).
+Without the opt-in, openclaw uses its built-in GitHub Copilot provider
+and never installs the runtime plugin.
+
+The runtime resolves the SDK in this order:
+
+1. `import("@github/copilot-sdk")` from the installed `@openclaw/copilot`
+   package.
+2. The well-known fallback dir `~/.openclaw/npm-runtime/copilot/` (the
+   legacy on-demand install target).
+
+A missing SDK surfaces a single error with code `COPILOT_SDK_MISSING`
+and the plugin reinstall command above.
+
+## Quickstart
+
+Pin one model (or one provider) to the harness:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: "github-copilot/gpt-5.5",
+      models: {
+        "github-copilot/gpt-5.5": {
+          agentRuntime: { id: "copilot" },
+        },
+      },
+    },
+  },
+}
+```
+
+Both routes are equivalent. Use `agentRuntime.id` on a single model entry
+when only that model should be routed through the harness; set
+`agentRuntime.id` on a provider when every model under that provider should
+use it.
+
+## Supported providers
+
+The harness advertises support for the canonical `github-copilot` provider
+(the same id owned by `extensions/github-copilot`):
+
+- `github-copilot`
+
+Anything outside that set falls through `selection.ts`'s `auto_pi` branch back
+to PI.
+
+## Auth
+
+Per-agent precedence, applied during `runCopilotAttempt`:
+
+1. **Explicit `useLoggedInUser: true`** on the attempt input. Uses the Copilot
+   CLI's logged-in user resolved under the agent's `copilotHome`.
+2. **Explicit `gitHubToken`** on the attempt input (with `profileId` +
+   `profileVersion`). Useful for direct CLI invocations and tests where the
+   caller wants to bypass auth-profile resolution.
+3. **Contract-resolved `resolvedApiKey` + `authProfileId`** from the
+   `EmbeddedRunAttemptParams` shape. This is the **production main path**:
+   core resolves the agent's configured `github-copilot` auth profile
+   (via `src/infra/provider-usage.auth.ts:resolveProviderAuths`) before
+   invoking the harness, and the harness consumes both fields directly.
+   This makes a `github-copilot:<profile>` auth profile work end-to-end
+   for headless / cron / multi-profile setups without env vars.
+4. **Env-var fallback** for direct CLI / dogfood runs where no auth
+   profile is configured. The runtime checks the following vars in
+   precedence order, mirroring the shipped `github-copilot` provider
+   (`extensions/github-copilot/auth.ts`) and the documented Copilot SDK
+   setup:
+   1. `OPENCLAW_GITHUB_TOKEN` -- harness-specific override; set this
+      to pin a token for the OpenClaw harness without disturbing
+      system-wide `gh` / Copilot CLI config.
+   2. `COPILOT_GITHUB_TOKEN` -- standard Copilot SDK / CLI env var.
+   3. `GH_TOKEN` -- standard `gh` CLI env var (matches the existing
+      `github-copilot` provider precedence).
+   4. `GITHUB_TOKEN` -- generic GitHub token fallback.
+
+   The first non-empty value wins; empty strings are treated as
+   absent. The synthesised pool profile id is `env:<NAME>` and the
+   profileVersion is a non-reversible sha256 fingerprint of the
+   token, so rotating the env value cleanly busts the client pool.
+
+5. **Default `useLoggedInUser`** when no token signal is available.
+
+Each agent gets a dedicated `copilotHome` so Copilot CLI tokens, sessions, and
+config do not leak between agents on the same machine. The default is
+`<agentDir>/copilot` when the host hands the harness an agent directory
+(isolating SDK state from OpenClaw's `models.json` / `auth-profiles.json` in
+the same directory), or `~/.openclaw/agents/<agentId>/copilot` otherwise.
+Override with `copilotHome: <path>` on the attempt input when you need a
+custom location (for example, a shared mount for migration).
+
+`probeCopilotAuthShape` (see [Doctor and probes](#doctor-and-probes)) is the
+pure shape check that validates which of the modes above will be used.
+It does not perform a live SDK handshake.
+
+## Configuration surface
+
+The harness reads its config from per-attempt input
+(`runCopilotAttempt({...})`) plus a small set of env defaults inside
+`extensions/copilot/src/`:
+
+- `copilotHome` — per-agent CLI state directory (defaults documented above).
+- `model` — string or `{ provider, id, api? }`. When omitted, OpenClaw uses
+  the agent's normal model selection and the harness verifies the resolved
+  provider is in the supported set.
+- `reasoningEffort` — `"low" | "medium" | "high" | "xhigh"`. Maps from
+  OpenClaw's `ThinkLevel` / `ReasoningLevel` resolution in
+  `auto-reply/thinking.ts`.
+- `infiniteSessionConfig` — optional override for the SDK
+  `infiniteSessions` block driven by `harness.compact`. Defaults are safe to
+  leave as-is.
+- `hooksConfig` — optional bridge config exposing OpenClaw
+  before/after-message-write hooks to the SDK loop.
+- `permissionPolicy` — optional override for the SDK's
+  `onPermissionRequest` handler used for built-in SDK tool kinds
+  (`shell`, `write`, `read`, `url`, `mcp`, `memory`, `hook`). Defaults
+  to `rejectAllPolicy` as a safety net; in practice the SDK never
+  invokes any of those kinds because every bridged OpenClaw tool is
+  registered with `overridesBuiltInTool: true` and
+  `skipPermission: true` so 100% of tool calls flow through OpenClaw's
+  wrapped `execute()`. See [Permissions and ask_user](#permissions-and-ask_user).
+- `enableSessionTelemetry` — opt-in OpenTelemetry routing via
+  `telemetry-bridge.ts`.
+
+Nothing in the rest of OpenClaw needs to know about these fields. Other
+plugins, channels, and core code only see the standard
+`AgentHarnessAttemptParams` / `AgentHarnessAttemptResult` shape.
+
+## Compaction
+
+When `harness.compact` runs, the Copilot SDK harness:
+
+1. Resumes the tracked SDK session without continuing pending work.
+2. Calls the SDK's session-scoped history compaction RPC.
+3. Returns the SDK compaction outcome without writing compatibility marker
+   files under the workspace.
+
+The OpenClaw side transcript mirror (see below) continues to receive the
+post-compaction messages, so user-facing chat history stays consistent.
+
+## Transcript mirroring
+
+`runCopilotAttempt` dual-writes each turn's mirrorable messages into the
+OpenClaw audit transcript via
+`extensions/copilot/src/dual-write-transcripts.ts`. The mirror is
+per-session scoped (`copilot:${sessionId}`) and uses a per-message
+identity (`${role}:${sha256_16(role,content)}`) so re-emits of prior-turn
+entries collide with existing on-disk keys and do not duplicate.
+
+The mirror is wrapped in two layers of failure containment so a transcript
+write failure cannot fail the attempt: an internal best-effort wrapper and a
+defense-in-depth `.catch(...)` at the attempt level. Failures are logged but
+not surfaced.
+
+## Side questions (`/btw`)
+
+`/btw` is **not** native on this harness. `createCopilotAgentHarness()`
+deliberately leaves `harness.runSideQuestion` undefined, so OpenClaw's `/btw`
+dispatcher (`src/agents/btw.ts`) falls through to the same in-tree PI fallback
+path it uses for every non-Codex runtime: the configured model provider is
+called directly with a short side-question prompt and streamed back via
+`streamSimple` (no CLI session, no extra pool slot).
+
+This keeps Copilot CLI sessions reserved for the agent's main turn loop, and
+keeps `/btw` behavior identical to other PI-backed runtimes. The contract is
+asserted in
+[`extensions/copilot/harness.test.ts`](https://github.com/openclaw/openclaw/blob/main/extensions/copilot/harness.test.ts)
+under `describe("runSideQuestion")`.
+
+## Doctor and probes
+
+`extensions/copilot/doctor-contract-api.ts` is auto-loaded by
+`src/plugins/doctor-contract-registry.ts`. It contributes:
+
+- An empty `legacyConfigRules` (no retired fields at MVP).
+- A no-op `normalizeCompatibilityConfig` (kept so future field retirements
+  have a stable in-tree home).
+- One `sessionRouteStateOwners` entry claiming provider `github-copilot`;
+  runtime `copilot`; CLI session key `copilot`; auth profile
+  prefix `github-copilot:`.
+
+`extensions/copilot/src/doctor-probes.ts` exports three imperative probes
+that hosts (including `openclaw doctor`) can call to verify the environment:
+
+| Probe                      | What it checks                                                                    | Reasons it can fail                                                              |
+| -------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `probeCopilotCliVersion`   | `copilot --version` exits 0 with a non-empty version string                       | `non-zero-exit`, `empty-version`, `spawn-failed`, `spawn-error`, `probe-timeout` |
+| `probeCopilotHomeWritable` | `mkdir -p copilotHome` + write + rm a marker file                                 | `copilothome-not-writable` (with the underlying fs error in `details.rawError`)  |
+| `probeCopilotAuthShape`    | At least one of `useLoggedInUser`, `gitHubToken`, or `profileId`+`profileVersion` | `no-auth-source`                                                                 |
+
+Each probe accepts a DI seam (`spawnFn`, `fsApi`) so tests do not spawn the
+real Copilot CLI or touch the host fs.
+
+## Limitations
+
+- The harness only claims the canonical `github-copilot` provider at MVP.
+  Additional providers (BYOK or otherwise) should land in follow-up PRs that
+  ship the adapter alongside the wire-up.
+- The harness does not deliver TUI; PI's TUI is unaffected and remains the
+  fallback for whatever runtimes do not have a peer surface.
+- PI session state is not migrated when an agent switches to `copilot`.
+  Selection is per attempt; existing PI sessions remain valid.
+- **Interactive `ask_user` is not yet wired.** The SDK's
+  `onUserInputRequest` handler is intentionally not registered, which
+  per the SDK contract hides the `ask_user` tool from the model
+  entirely. Agents running under this harness make best-judgment
+  decisions from the initial prompt rather than asking clarifying
+  questions mid-turn. A follow-up will port the codex pattern at
+  `extensions/codex/src/app-server/user-input-bridge.ts` to route SDK
+  `UserInputRequest`s through the OpenClaw channel/TUI prompt path; the
+  dormant scaffolding in `extensions/copilot/src/user-input-bridge.ts`
+  is the surface that follow-up will wire.
+
+## Permissions and ask_user
+
+Permission enforcement for bridged OpenClaw tools happens **inside the
+tool wrapper**, not via the SDK's `onPermissionRequest` callback. The
+same `wrapToolWithBeforeToolCallHook` that PI uses
+(`src/agents/pi-tools.before-tool-call.ts`) is applied by
+`createOpenClawCodingTools` to every coding tool: loop detection,
+trusted plugin policies, before-tool-call hooks, and two-phase plugin
+approvals via the gateway (`plugin.approval.request`) all run with the
+exact same code path as native PI attempts.
+
+To let that wrapper own the decision, the SDK Tool returned by
+`convertOpenClawToolToSdkTool` is marked with:
+
+- `overridesBuiltInTool: true` — replaces the Copilot CLI's built-in
+  tool of the same name (edit, read, write, bash, …) so every tool
+  invocation routes back to OpenClaw.
+- `skipPermission: true` — tells the SDK not to fire
+  `onPermissionRequest({kind: "custom-tool"})` before invoking the tool.
+  The wrapped `execute()` performs the richer OpenClaw policy check
+  internally; an SDK-level prompt would either short-circuit OpenClaw's
+  enforcement (if we allow-all) or block every tool call (if we
+  reject-all) — neither matches PI parity.
+
+The in-tree codex harness uses the same split: bridged OpenClaw tools
+are wrapped (`extensions/codex/src/app-server/dynamic-tools.ts`) and
+the codex-app-server's _own_ native approval kinds
+(`item/commandExecution/requestApproval`,
+`item/fileChange/requestApproval`,
+`item/permissions/requestApproval`) are routed through
+`plugin.approval.request`
+(`extensions/codex/src/app-server/approval-bridge.ts`). The Copilot SDK
+equivalent — fail-closed `rejectAllPolicy` for any non-`custom-tool`
+kind that ever reaches `onPermissionRequest` — is the same safety net,
+and it does not fire in practice because `overridesBuiltInTool: true`
+displaces every built-in.
+
+For the wrapped-tool layer to make policy decisions equivalent to PI,
+the harness forwards the full PI attempt-tool context to
+`createOpenClawCodingTools` — identity (`senderIsOwner`,
+`memberRoleIds`, `ownerOnlyToolAllowlist`, …), channel/routing
+(`groupId`, `currentChannelId`, `replyToMode`, message-tool toggles),
+auth (`authProfileStore`), run identity
+(`sessionKey`/`runSessionKey` derived from `sandboxSessionKey`,
+`runId`), model context (`modelApi`, `modelContextWindowTokens`,
+`modelCompat`, `modelHasVision`), and run hooks (`onToolOutcome`,
+`onYield`). Without those fields, owner-only allowlists silently
+behave as deny-by-default, plugin-trust policies cannot resolve to the
+right scope, and `session_status: "current"` resolves to a stale
+sandbox key. The bridge builder is in
+`extensions/copilot/src/tool-bridge.ts` and mirrors the PI
+authoritative call at
+`src/agents/pi-embedded-runner/run/attempt.ts:1029-1117`. Two PI fields
+are intentionally **not** forwarded at MVP and tracked as follow-ups:
+`sandbox` (the harness does not yet route through `resolveSandboxContext`)
+and the PI tool-search/code-mode machinery
+(`toolSearchCatalogRef`, `includeCoreTools`,
+`includeToolSearchControls`, `toolSearchCatalogExecutor`,
+`toolConstructionPlan`), which has no analog at the SDK boundary.
+
+### Session-level GitHub token
+
+The Copilot SDK contract distinguishes the **client-level** GitHub
+token (`CopilotClientOptions.gitHubToken`, used to authenticate the
+CLI process itself) from the **session-level** token
+(`SessionConfig.gitHubToken`, which determines content exclusion,
+model routing, and quota for that session and is honored on both
+`createSession` and `resumeSession`). The harness resolves auth once
+via `resolveCopilotAuth` and sets both fields when the auth mode is
+`gitHubToken` (an explicit `auth.gitHubToken` or a contract-resolved
+`resolvedApiKey` from a configured `github-copilot` auth profile).
+When the resolved mode is `useLoggedInUser`, the session-level field
+is omitted so the SDK keeps deriving identity from the logged-in
+identity.
+
+`ask_user` is intentionally hidden — see Limitations above.
+
+## Related
+
+- [Agent runtimes](/concepts/agent-runtimes)
+- [Codex harness](/plugins/codex-harness)
+- [Agent harness plugins (SDK reference)](/plugins/sdk-agent-harness)

package/docs/plugins/dependency-resolution.md

@@ -0,0 +1,176 @@
+---
+summary: "How OpenClaw installs plugin packages and resolves plugin dependencies"
+read_when:
+  - You are debugging plugin package installs
+  - You are changing plugin startup, doctor, or package-manager install behavior
+  - You are maintaining packaged OpenClaw installs or bundled plugin manifests
+title: "Plugin dependency resolution"
+sidebarTitle: "Dependencies"
+---
+
+OpenClaw keeps plugin dependency work at install/update time. Runtime loading
+does not run package managers, repair dependency trees, or mutate the OpenClaw
+package directory.
+
+## Responsibility split
+
+Plugin packages own their dependency graph:
+
+- runtime dependencies live in the plugin package `dependencies` or
+  `optionalDependencies`
+- SDK/core imports are peer or supplied OpenClaw imports
+- local development plugins bring their own already-installed dependencies
+- npm and git plugins are installed into OpenClaw-owned package roots
+
+OpenClaw owns only the plugin lifecycle:
+
+- discover the plugin source
+- install or update the package when explicitly requested
+- record the install metadata
+- load the plugin entrypoint
+- fail with an actionable error when dependencies are missing
+
+## Install roots
+
+OpenClaw uses stable per-source roots:
+
+- npm packages install into per-plugin projects under
+  `~/.openclaw/npm/projects/<encoded-package>`
+- git packages clone under `~/.openclaw/git`
+- local/path/archive installs are copied or referenced without dependency repair
+
+npm installs run in that per-plugin project root with:
+
+```bash
+cd ~/.openclaw/npm/projects/<encoded-package>
+npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund
+```
+
+`openclaw plugins install npm-pack:<path.tgz>` uses that same per-plugin npm
+project root for a local npm-pack tarball. OpenClaw reads the tarball's npm
+metadata, adds it to the managed project as a copied `file:` dependency, runs
+the normal npm install, and then verifies the installed lockfile metadata before
+trusting the plugin.
+This is intended for package-acceptance and release-candidate proof where a
+local pack artifact should behave like the registry artifact it simulates.
+
+npm may hoist transitive dependencies to the per-plugin project's
+`node_modules` beside the plugin package. OpenClaw scans the managed project
+root before trusting the install and removes that project during uninstall, so
+hoisted runtime dependencies stay inside that plugin's cleanup boundary.
+
+Published npm plugin packages can ship `npm-shrinkwrap.json`. npm uses that
+publishable lockfile during install, and OpenClaw's managed npm project root
+supports it through the normal npm install path. OpenClaw-owned publishable
+plugin packages must include a package-local shrinkwrap generated from that
+plugin package's published dependency graph:
+
+```bash
+pnpm deps:shrinkwrap:generate
+pnpm deps:shrinkwrap:check
+```
+
+The generator strips plugin `devDependencies`, applies the workspace override
+policy, and writes `extensions/<id>/npm-shrinkwrap.json` for each
+`publishToNpm` plugin. Third-party plugin packages may also ship shrinkwrap;
+OpenClaw does not require it for community packages, but npm will respect it
+when present.
+
+OpenClaw-owned npm plugin packages can also publish with explicit
+`bundledDependencies`. The npm publish path overlays the runtime dependency
+name list, removes dev-only workspace metadata from the published package
+manifest, runs a script-free npm install for package-local runtime
+dependencies, then packs or publishes the plugin tarball with those dependency
+files included. Native-heavy packages, including Codex and ACP runtimes, opt out
+with `openclaw.release.bundleRuntimeDependencies: false`; those packages still
+ship their shrinkwrap, but npm resolves runtime dependencies during install
+instead of embedding every platform binary in the plugin tarball. The root
+`openclaw` package does not bundle its full dependency tree.
+
+Plugins that import `openclaw/plugin-sdk/*` declare `openclaw` as a peer
+dependency. OpenClaw does not let npm install a separate registry copy of the
+host package into a managed project, because stale host packages can affect npm
+peer resolution inside that plugin. Managed npm installs skip npm peer
+resolution/materialization and OpenClaw reasserts plugin-local
+`node_modules/openclaw` links for installed packages that declare the host peer
+after install or update.
+
+git installs clone or refresh the repository, then run:
+
+```bash
+npm install --omit=dev --ignore-scripts --no-audit --no-fund
+```
+
+The installed plugin then loads from that package directory, so package-local
+and parent `node_modules` resolution works the same way it does for a normal
+Node package.
+
+## Local plugins
+
+Local plugins are treated as developer-controlled directories. OpenClaw does not
+run `npm install`, `pnpm install`, or dependency repair for them. If a local
+plugin has dependencies, install them in that plugin before loading it.
+
+Third-party TypeScript local plugins can use the emergency Jiti path. Packaged
+JavaScript plugins and bundled internal plugins load through native
+import/require instead of Jiti.
+
+## Startup and reload
+
+Gateway startup and config reload never install plugin dependencies. They read
+the plugin install records, compute the entrypoint, and load it.
+
+If a dependency is missing at runtime, the plugin fails to load and the error
+should point the operator to an explicit fix:
+
+```bash
+openclaw plugins update <id>
+openclaw plugins install <source>
+openclaw doctor --fix
+```
+
+`doctor --fix` can clean legacy OpenClaw-generated dependency state and recover
+downloadable plugins that are missing from the local install records when config
+references them. Doctor does not repair dependencies for an already-installed
+local plugin.
+
+## Bundled plugins
+
+Lightweight and core-critical bundled plugins are shipped as part of OpenClaw.
+They should either have no heavy runtime dependency tree or be moved out to a
+downloadable package on ClawHub/npm.
+
+For the current generated list of plugins that ship in the core package, install
+externally, or stay source-only, see [Plugin inventory](/plugins/plugin-inventory).
+
+Bundled plugin manifests must not request dependency staging. Large or optional
+plugin functionality should be packaged as a normal plugin and installed through
+the same npm/git/ClawHub path as third-party plugins.
+
+In source checkouts, OpenClaw treats the repository as a pnpm monorepo. After
+`pnpm install`, bundled plugins load from `extensions/<id>` so package-local
+workspace dependencies are available and edits are picked up directly. Source
+checkout development is pnpm-only; plain `npm install` at the repository root is
+not a supported way to prepare bundled plugin dependencies.
+
+| Install shape                    | Bundled plugin location               | Dependency owner                                                     |
+| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
+| `npm install -g openclaw`        | Built runtime tree inside the package | OpenClaw package and explicit plugin install/update/doctor flows     |
+| Git checkout plus `pnpm install` | `extensions/<id>` workspace packages  | The pnpm workspace, including each plugin package's own dependencies |
+| `openclaw plugins install ...`   | Managed npm project/git/ClawHub root  | The plugin install/update flow                                       |
+
+## Legacy cleanup
+
+Older OpenClaw versions generated bundled-plugin dependency roots at startup or
+during doctor repair. Current doctor cleanup removes those stale directories and
+symlinks when `--fix` is used, including old `plugin-runtime-deps` roots, global
+Node-prefix package symlinks that point at pruned `plugin-runtime-deps` targets,
+`.openclaw-runtime-deps*` manifests, generated plugin `node_modules`, install
+stage directories, and package-local pnpm stores. Packaged postinstall also
+removes those global symlinks before pruning the legacy target roots so upgrades
+do not leave dangling ESM package imports.
+
+Older npm installs also used a shared `~/.openclaw/npm/node_modules` root.
+Current install, update, uninstall, and doctor flows still recognize that legacy
+flat root only for recovery and cleanup. New npm installs should create
+per-plugin project roots instead.