fengming 0.3.9 → 0.3.11

package/docs/plugins/copilot.md

@@ -1,356 +0,0 @@
----
-summary: "Run FengMing 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 / fengming / copilot) and want it to run through the Copilot CLI
----
-
-The external `@fengming/copilot` plugin lets FengMing 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`.
-FengMing still owns chat channels, session files, model selection, FengMing
-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 `fengming doctor`.
-
-For the broader model/provider/runtime split, start with
-[Agent runtimes](/concepts/agent-runtimes).
-
-## Requirements
-
-- FengMing with the `@fengming/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 `@fengming/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
-  `~/.fengming/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.
-
-`fengming 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 `fengming` 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
-fengming plugins install @fengming/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, fengming 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 `@fengming/copilot`
-   package.
-2. The well-known fallback dir `~/.fengming/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. `FENGMING_GITHUB_TOKEN` -- harness-specific override; set this
-      to pin a token for the FengMing 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 FengMing's `models.json` / `auth-profiles.json` in
-the same directory), or `~/.fengming/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, FengMing 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
-  FengMing'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 FengMing
-  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 FengMing tool is
-  registered with `overridesBuiltInTool: true` and
-  `skipPermission: true` so 100% of tool calls flow through FengMing'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 FengMing 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. Enables `infiniteSessions` on the SDK session.
-2. Lets the SDK perform its native compaction.
-3. Writes an FengMing-shaped marker at
-   `workspacePath/files/fengming-compaction-<ts>.json` so existing FengMing
-   transcript readers still see a familiar artifact.
-
-The FengMing 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
-FengMing 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 FengMing'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/fengming/fengming/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 `fengming 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 FengMing 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 FengMing 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
-`createFengMingCodingTools` 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
-`convertFengMingToolToSdkTool` 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 FengMing.
-- `skipPermission: true` — tells the SDK not to fire
-  `onPermissionRequest({kind: "custom-tool"})` before invoking the tool.
-  The wrapped `execute()` performs the richer FengMing policy check
-  internally; an SDK-level prompt would either short-circuit FengMing'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 FengMing 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
-`createFengMingCodingTools` — 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

@@ -1,176 +0,0 @@
----
-summary: "How FengMing 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 FengMing installs or bundled plugin manifests
-title: "Plugin dependency resolution"
-sidebarTitle: "Dependencies"
----
-
-FengMing keeps plugin dependency work at install/update time. Runtime loading
-does not run package managers, repair dependency trees, or mutate the FengMing
-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 FengMing imports
-- local development plugins bring their own already-installed dependencies
-- npm and git plugins are installed into FengMing-owned package roots
-
-FengMing 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
-
-FengMing uses stable per-source roots:
-
-- npm packages install into per-plugin projects under
-  `~/.fengming/npm/projects/<encoded-package>`
-- git packages clone under `~/.fengming/git`
-- local/path/archive installs are copied or referenced without dependency repair
-
-npm installs run in that per-plugin project root with:
-
-```bash
-cd ~/.fengming/npm/projects/<encoded-package>
-npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund
-```
-
-`fengming plugins install npm-pack:<path.tgz>` uses that same per-plugin npm
-project root for a local npm-pack tarball. FengMing 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. FengMing 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 FengMing's managed npm project root
-supports it through the normal npm install path. FengMing-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;
-FengMing does not require it for community packages, but npm will respect it
-when present.
-
-FengMing-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 `fengming.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
-`fengming` package does not bundle its full dependency tree.
-
-Plugins that import `fengming/plugin-sdk/*` declare `fengming` as a peer
-dependency. FengMing 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 FengMing reasserts plugin-local
-`node_modules/fengming` 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. FengMing 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
-fengming plugins update <id>
-fengming plugins install <source>
-fengming doctor --fix
-```
-
-`doctor --fix` can clean legacy FengMing-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 FengMing.
-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, FengMing 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 fengming`        | Built runtime tree inside the package | FengMing 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 |
-| `fengming plugins install ...`   | Managed npm project/git/ClawHub root  | The plugin install/update flow                                       |
-
-## Legacy cleanup
-
-Older FengMing 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,
-`.fengming-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 `~/.fengming/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.