Native plugin from main fails to start MCP servers, and its pinned repair command (npx -y nsolid-plugin@1.0.3 setup) cannot fix it #69

Summary

The Claude Code / Codex / Antigravity native plugin is installed from the default branch of this repo. main (c36d50f) still says version 1.0.3 in every manifest, but its scripts/mcp-wrapper.js is not the wrapper that was tagged and published as 1.0.3. The post-tag wrapper (from #63 / 2a89325, the fix for #61) no longer falls back to npx mcp-remote. It requires a managed bridge runtime at ~/.agents/nsolid-plugin/runtime/mcp-remote/0.1.38/, and only nsolid-plugin setup provisions that runtime.

When the runtime is missing, the wrapper prints a repair command pinned to its own version string:

[nsolid-plugin] MCP bridge runtime is not ready. Run: npx -y nsolid-plugin@1.0.3 setup --harness claude

The published nsolid-plugin@1.0.3 on npm was built before 2a89325. It has no runtime provisioning at all, so running the suggested command never creates the runtime and the error comes back on the next start.

Impact

• Any native-plugin user without the managed runtime gets no N|Solid MCP servers (nsolid-console, ncm, ns-benchmark). That covers fresh installs where setup was last run with npm 1.0.3 or earlier, and any case where the runtime was removed or is corrupt. Every MCP-backed skill stops working.
• The official repair path is a dead end. The command the wrapper prints and the README's troubleshooting section ("The repair command is pinned to the plugin version that generated the wrapper, so rerunning it repairs exactly the wrapper that printed it", README.md:241) both send users to a CLI that cannot do the repair.
• The version string 1.0.3 now covers two incompatible wrapper implementations: tag v1.0.3, which uses an npx fallback, and main, which requires the managed runtime. That makes version-based support and diagnosis unreliable.

Steps to reproduce

1. On a machine with no ~/.agents/nsolid-plugin/runtime/ directory, install the native plugin:
   claude plugin marketplace add NodeSource/nsolid-plugin && claude plugin install nsolid-plugin@nodesource
   (installed_plugins.json records "version": "1.0.3", "gitCommitSha": "c36d50f…").
2. Start Claude Code. The three MCP servers fail to connect. Running the wrapper directly shows why:
   node <plugin cache>/nsolid-plugin/1.0.3/scripts/mcp-wrapper.js ncm claude
   prints MCP bridge runtime is not ready. Run: npx -y nsolid-plugin@1.0.3 setup --harness claude.
3. Run npx -y nsolid-plugin@1.0.3 setup --harness claude. It authenticates and exits successfully.
4. ~/.agents/nsolid-plugin/runtime/mcp-remote/0.1.38/ still does not exist. Restart the harness and the same error appears.

Reproduced locally on Windows 11 with the plugin cached from c36d50f.

Expected

The repair command printed by a wrapper points to a published CLI that provisions the runtime that wrapper validates.

Actual

The repair command points to npm nsolid-plugin@1.0.3, which predates runtime provisioning.

Root cause / evidence

• scripts/mcp-wrapper.js:18-19 on main: MCP_REMOTE_VERSION = "0.1.38", PLUGIN_VERSION = "1.0.3". :139-145 builds npx -y nsolid-plugin@${PLUGIN_VERSION} setup. :148-151 accepts only the managed runtime (the dev fallback is behind NSOLID_MCP_RUNTIME_DEV_FALLBACK=1).
• git show v1.0.3:scripts/mcp-wrapper.js: the tagged 1.0.3 wrapper used npx -y mcp-remote@0.1.38 and an unpinned setup command.
• git log v1.0.3..origin/main lists 22 commits that shipped to native-plugin users without a version bump, including 2a89325 fix(mcp): provision bridge runtime during setup, 86cd139 (new ns-download-asset skill) and c36d50f (Codex bootstrap).
• npm pack nsolid-plugin@1.0.3: dist/src/mcp/ contains only mcp-config-merger, mcp-config-writer and mcp-tracker. There is no mcp-remote-runtime, and setup help reads "Authenticate with NodeSource (may open a browser)". nsolid-plugin@1.1.0 does ship dist/src/mcp/mcp-remote-runtime.js with MCP_REMOTE_VERSION = '0.1.38'.
• npm publish times: 1.0.3 at 2026-08-25T20:09Z (tag 02ffc14). 1.1.0 at 2026-09-16 from an unmerged branch (see the separate release-drift issue).

Workaround: npx -y nsolid-plugin@latest setup --harness <harness>. Unpinned 1.1.0 provisions the same mcp-remote 0.1.38 runtime and uses the same ~/.agents/.nodesource-auth.json, so it works with the main-branch wrapper.

Suggested fix

• Cut a release from main now (for example 1.0.4) and publish it to npm, so that nsolid-plugin@<manifest version> provisions the runtime the wrapper expects. Bump bundle.json and regenerate the manifests so the wrapper pins the new version.
• Add a CI or release check that fails when bundle.json's version is already published to npm from a different commit, or when wrapper or skill content changes without a version bump. This fits the release tooling proposed in Add version-aware CLI and harness update workflow #53.
• Optionally, add an "if the pinned setup doesn't fix this, run npx -y nsolid-plugin@latest setup" hint to the README troubleshooting entry.

Found while writing the plugin docs page in nodesource/nsdocs#110.