fix: preserve VS Code JSONC configurations through MCP lifecycle (#260)

* fix: preserve realistic VS Code JSONC configurations

* fix: preserve JSONC removal and bind candidate dist files

* test: retain Claude post-removal native evidence

* test: synchronize native cancellation with actual wire call

* docs: record independently verified realistic native validation

Author: m1ngshum

CHANGELOG.md

@@ -8,6 +8,21 @@ _Add entries here, never under a stamped version_ — a release commit renames t
 heading, and a branch that wrote beneath it merges without conflict straight into a
 published section (it happened to #170).
 
+### Fixed
+
+- VS Code user-global `mcp.json` accepts comments and trailing commas. Install,
+  guard, update, toggle and remove edit only the selected server, preserving
+  unrelated configuration/comments and the original raw backup. Invalid JSONC
+  and ambiguous duplicate server paths refuse before writes. Other clients keep
+  strict JSON parsing; managed configuration locations are unchanged.
+
+### Added
+
+- Explicit candidate-artifact native validation, with archive integrity and
+  complete executable file-set hashes, plus realistic JSONC/input/environment-variable fixtures.
+  The default published baseline remains 0.47.1; live model and normal approval
+  behavior remain outside these tests.
+
 ## [0.47.2] - 2026-10-12
 
 PATCH by content: native-client test tooling and documentation only; production

CLAUDE.md

@@ -34,7 +34,21 @@ repinned to actual 0.47.2 passes 40 comparisons, with zero failures, two expecte
 unsupported combinations and seven self-checks; its locked integrity matches
 the verified npm tarball. The committed harness baselines remain unchanged.
 
-**Native validation tooling:** `scripts/native-client/` retains published mcpm
+**Unreleased Phase 2B:** VS Code user-global configuration reads JSONC and edits
+only the selected server while preserving unrelated bytes/comments and the raw
+backup. Invalid/duplicate server paths fail before writes; other clients remain
+strict JSON. Microsoft `jsonc-parser` 3.3.1 is the sole new production dependency.
+The explicit native candidate mode binds archive/lock/package/complete dist-file
+identity and exercises actual client input/environment expansion. Independent
+final candidate and default published-baseline runs both pass 8/8 VS Code and
+7/7 Claude Code, with matching hashes, raw preservation and cleanup. Source
+checks: 3,588 tests, typecheck/build and 13 harness self-checks pass. Astra fixed
+inherited-key removal, incomplete chunk binding and a pre-wire cancellation
+fixture race; cancellation requires the current matching request before firing.
+User-global paths are unchanged; portable/Agent Host routes and normal approval,
+provider/model/usage-skill behavior remain unverified.
+
+**Released native validation baseline (v0.47.2):** `scripts/native-client/` retains published mcpm
 0.47.1 as its fixed baseline. VS Code 1.141.0 passed 8/8 and Claude Code 2.1.296
 passed 7/7 in separate disposable macOS 26.6.2/arm64 VMs, independently repeated
 against the final reviewed harness with matching host/guest hashes and cleanup.

CONTRIBUTING.md

@@ -68,6 +68,8 @@ For installed VS Code/Claude Code checks inside disposable macOS VMs, see
 [native client validation](docs/NATIVE-CLIENT-VALIDATION.md). Its fixture/evidence
 self-checks run with `node --test scripts/native-client/self-check.mjs`; native
 VM runs require the separately pinned public client/runtime payload.
+Candidate changes must use the explicit candidate mode and a fresh packed CLI;
+a passing published-baseline run does not validate changed production code.
 
 ## Ground rules
 

README.md

@@ -594,6 +594,13 @@ permission grants, model subscription or external decision service.
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 | Gemini CLI | `~/.gemini/settings.json` (user-global `mcpServers`) |
 
+VS Code's managed `mcp.json` supports JSONC comments and trailing commas. Changes
+edit the selected server while preserving unrelated settings/comments and the
+original backup. Other clients retain strict JSON parsing. Variable references
+are retained for the client to resolve. Portable/workspace configurations and
+Copilot Agent Host configuration paths are not managed by these adapters; see
+the [native validation scope](docs/NATIVE-CLIENT-VALIDATION.md).
+
 Linux and Windows paths are also supported. See `mcpm doctor` to verify which clients are detected on your system.
 
 ## How it works

docs/GUARD.md

@@ -253,7 +253,7 @@ Use during debugging when guard is in the way and you want to turn it off withou
 ### `mcpm guard cleanup [--yes]`
 Prunes pin entries for servers no longer installed in any client config. Dry-run by default; pass `--yes` to apply.
 
-A server whose config entry is malformed still counts as installed, so its pin is kept. A detected client's config that **cannot be read** (unparseable — mcpm reads configs as strict JSON, so comments and trailing commas count — or a permission error, including on the directory that holds it) holds servers cleanup cannot see. So if any pin is held by no readable config, cleanup refuses — in the dry run and with `--yes` alike — names each unreadable client, its config path and the error, prunes nothing, and exits `1`: that pin cannot be told apart from one belonging to a live server there, and pruning it would erase the server's rug-pull baseline. Fix the config and re-run. If every pin is held by a readable config, the unreadable one cannot change the result: cleanup reports nothing to prune, notes the unreadable config, and exits `0`. A client with no config file at all is not an error. A refusal because `pins.json` fails its integrity check also exits `1`.
+A server whose config entry is malformed still counts as installed, so its pin is kept. A detected client's config that **cannot be read** (unparseable — VS Code permits JSONC comments/trailing commas, while the other clients use strict JSON — or a permission error, including on the directory that holds it) holds servers cleanup cannot see. So if any pin is held by no readable config, cleanup refuses — in the dry run and with `--yes` alike — names each unreadable client, its config path and the error, prunes nothing, and exits `1`: that pin cannot be told apart from one belonging to a live server there, and pruning it would erase the server's rug-pull baseline. Fix the config and re-run. If every pin is held by a readable config, the unreadable one cannot change the result: cleanup reports nothing to prune, notes the unreadable config, and exits `0`. A client with no config file at all is not an error. A refusal because `pins.json` fails its integrity check also exits `1`.
 
 ### `mcpm guard inspect [file] [--json]`
 

docs/NATIVE-CLIENT-VALIDATION.md

@@ -38,6 +38,63 @@ archive hashes and installs npm dependencies with lifecycle scripts disabled.
 Claude Code's reviewed, pinned native-binary installer runs inside the offline
 guest to connect its preloaded platform binary to the CLI entry point.
 
+### Test a candidate with realistic configuration
+
+Build and pack the current checkout, then explicitly prepare/run that artifact:
+
+```sh
+mkdir -p /tmp/mcpm-candidate
+pnpm build
+pnpm pack --pack-destination /tmp/mcpm-candidate
+node scripts/native-client/prepare.mjs /tmp/mcpm-candidate-payload /tmp/mcpm-candidate/getmcpm-cli-0.15.0.tgz
+node scripts/native-client/run-vm.mjs /path/to/tart \
+  /tmp/mcpm-native-vms /tmp/mcpm-candidate-payload /tmp/mcpm-candidate-evidence \
+  --candidate --realistic-config
+```
+
+The source package uses placeholder version 0.15.0; that candidate is not the
+published 0.15.0 release. `cliArtifact.kind`, archive SHA-256/SHA-512, lock integrity
+and installed file hashes identify it. Candidate mode verifies that the package
+manifest and complete `dist` file set/bytes match the archive (including lazy
+chunks, missing files and extra files), and that guest/host identities agree. It
+does not establish source provenance; record the source revision/diff used for
+the fresh build separately. The default published baseline and pins are unchanged.
+Candidate preparation freezes its own dependency lock with scripts disabled.
+
+The realistic suite adds comments/trailing commas and input declarations to VS
+Code's actual user-global file. Ordinary declared environment values use client
+variable references, including quotes/backslashes; VS Code also resolves a known
+synthetic input prompt. Claude Code exercises environment/default references in
+its user-global file. Echo replies must contain the exact resolved values before
+and after wrapping/update. Raw backup bytes, input declarations and unrelated
+comments/settings must survive the lifecycle. All eight/seven baseline case
+requirements still apply. The helper accepts only the named fixture prompt with
+its exact prefilled synthetic value; account/sign-in prompts remain excluded.
+
+VS Code parsing uses Microsoft's `jsonc-parser`, checks every parse error and
+rejects duplicate server containers/names before edits. Only the managed entry
+is edited; removal can retain a legal trailing comma. Other clients continue
+to use strict JSON. This does not migrate configuration scopes or resolve
+variables inside mcpm.
+
+Current [VS Code documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+prefers portable `.mcp.json`/Copilot global locations and distinguishes Agent Host
+routing. This harness still measures the adapter's user-profile `mcp.json` through
+the native Tool API. Portable/workspace paths, alternate profiles and Agent Host
+chat routing remain separate, unverified integration paths.
+
+Reviewed and independently repeated local measurements on 2026-10-12 passed
+**8/8 VS Code and 7/7 Claude Code** in both the realistic candidate suite and the
+unchanged published-baseline mode. These use macOS 26.6.2/arm64 and the named
+client versions below. Host/guest hashes, all 134 candidate distribution files,
+raw configuration/backups, actual variable bindings, correlated cancellation,
+post-removal receipts and cleanup were checked. All 3,588 source tests,
+typecheck/build and 13 harness self-checks passed. Astra fixed inherited-key
+server removal, incomplete candidate chunk identity and a pre-wire cancellation
+fixture race; cancellation now waits for the current slow request before firing.
+The managed server entry can be reformatted; comments/settings outside it and
+the original raw backup are preserved.
+
 ## Boundary and fixture scope
 
 The runner clones the immutable image independently for **VS Code first, then
@@ -102,7 +159,7 @@ VS Code completion for drift. A separate interrupted VM run verifies cleanup.
 | Install and echo | mcpm writes the actual global file; native opening identifies the client and a real tool call returns the exact nonce/version/marker. |
 | Enable, block and recovery | The app loads the wrapped launcher; attack content produces the guard block message, then an echo succeeds. Declaration/tool pins contain real hashes. |
 | Warn and forward | The existing Unicode-warning fixture arrives unchanged and the guard records its expected warning signature. |
-| Cancel and recover | VS Code forwards correlated cancellation and continues. Claude Code is deliberately interrupted during a real slow call; a new invocation succeeds. A deadline alone cannot count as cancellation. |
+| Cancel and recover | VS Code waits up to 10 seconds for its current slow call to reach the peer, then forwards correlated cancellation and continues. Claude Code is deliberately interrupted during a real slow call; a new invocation succeeds. A deadline or cancellation before the wire call cannot count as success. |
 | VS Code reload | A real window reload reestablishes MCP; the repeated echo has a different peer PID. |
 | Update | The public CLI updates the fixture package coordinate while retaining the guard, extra arguments, environment and unrelated configuration. The native tool reports 2.0.0. |
 | Schema drift | Changed tool schema is blocked, no call reaches the peer, pins remain unchanged, and the attempt finishes without a deadline kill. Reverting the fixture restores a successful native call. |
@@ -114,7 +171,9 @@ hashes, and rejects empty/incomplete success reports or missing/reused
 observations. Per-case JSON records include execution status/deadlines, client receipts, synthetic wire
 traffic, configuration, pins and events from that invocation. Each observation
 has a unique filename linked from its case; recovery calls cannot overwrite
-earlier evidence. `manifest.json` identifies pins, flags, VM configuration,
+earlier evidence. The final removal observation includes raw configuration and
+backup bytes; Claude Code also exports its `mcp get` not-found receipt.
+`manifest.json` identifies pins, flags, VM configuration,
 all guest fixture/extension hashes, host harness hashes and cleanup.
 Read failures and unexpected client behavior are
 failures; they are not silently classified as unsupported.
@@ -133,7 +192,7 @@ evidence local; publish scoped results rather than entire client transcripts.
 ## Remaining verification
 
 Live providers and actual model/usage-skill behavior, interactive chat/default
-approval workflows, other clients/platforms, JSONC/input-variable configuration,
+approval workflows, other clients/platforms, additional configuration variants,
 and complete protocol conformance remain unverified. Native client versions
 and observed wire protocol must be recorded rather than inferred from package
 versions. Updating pins requires repeating the native matrix. SIGKILL, host

package.json

@@ -80,6 +80,7 @@
     "chalk": "^6.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
+    "jsonc-parser": "^3.3.1",
     "ora": "^9.4.0",
     "proper-lockfile": "^4.1.2",
     "semver": "^7.8.1",

pnpm-lock.yaml

@@ -1,3 +1,9 @@
+export const fixtureInputPrompt = 'native-fixture synthetic input';
+export const fixtureInputValue = 'synthetic input "quoted" \\ path';
+export function fixtureInput(widget) {
+  return !/sign.?in|account|oauth|authentication/i.test(widget.text) && widget.text.includes(fixtureInputPrompt) && widget.value === fixtureInputValue;
+}
+
 export function fixtureApproval(dialog) {
   if (/sign.?in|account|oauth|authentication/i.test(dialog.text)) return undefined;
   if (!/Enable global auto approve\?/.test(dialog.text) && !/native-fixtur/.test(dialog.text)) return undefined;
@@ -32,6 +38,11 @@ export async function approveFixtureDialogs(port, log, signal) {
           const clicked = await evaluate(`(()=>{const d=Array.from(document.querySelectorAll('.monaco-dialog-box')).find(d=>d.innerText===${JSON.stringify(dialog.text)});const b=d&&Array.from(d.querySelectorAll('.monaco-button')).find(b=>b.innerText===${JSON.stringify(button)});if(b&&b.getAttribute('aria-disabled')!=='true'){b.click();return true;}return false;})()`);
           if (clicked) log.push({ text: dialog.text, button });
         }
+        const widgets = await evaluate("Array.from(document.querySelectorAll('.quick-input-widget')).filter(w=>w.offsetWidth>0).map(w=>({text:w.innerText,value:w.querySelector('input')?.value}))");
+        if ((widgets || []).some(fixtureInput)) {
+          for (const type of ['keyDown', 'keyUp']) ws.send(JSON.stringify({ id: Math.floor(Math.random() * 1000000), method: 'Input.dispatchKeyEvent', params: { type, key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 } }));
+          log.push({ inputPrompt: fixtureInputPrompt, value: fixtureInputValue });
+        }
       }
     } catch (e) { if (signal.aborted) return; }
     finally { ws?.close(); }