@junghanacs/entwurf 0.12.1 → 0.12.2

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented here. Format follows [Kee
 
 ## Unreleased
 
+## 0.12.2 — 2026-06-29
+
+### Fixed
+
+- **Claude Code meta-bridge installs on the supported 2.1.x floor.** Claude's plugin validator is a closed schema whose accepted marketplace keys differ by patch level; 0.12.1's root-level `marketplace.json` `description` passed on Claude 2.1.195 but failed on the floor host's 2.1.97 with `Unrecognized key: "description"`. The marketplace manifest now keeps only the minimal root keyset confirmed on the floor (`name`, `owner`, `plugins`), leaving explanatory text in installer/docs comments rather than in closed-schema JSON.
+- **Installed meta-bridge MCP wiring no longer bakes pnpm store paths.** On npm/pnpm-installed hosts, the user-scope Claude MCP entry now points at the stable `entwurf-bridge` bin instead of `$REPO/mcp/entwurf-bridge/start.sh`, whose `$REPO` can be a `.pnpm/@junghanacs+entwurf@.../node_modules/...` hash path that goes stale on version or peer changes. Development clones still pin to that clone's `start.sh`; both branches preserve the external Claude sender env (`ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code`, `ENTWURF_BRIDGE_REQUIRE_META_SENDER=1`).
+
+### Added
+
+- **`check-meta-manifest-schema` — a CLI-version-independent meta-bridge manifest guard.** The new deterministic gate pins the Claude marketplace/plugin/hooks manifests to the minimal keysets used by the meta-bridge, including the load-bearing hook event names (`SessionStart`, `CwdChanged`, `UserPromptSubmit`, `FileChanged`) and hook command keys. It also asserts `meta-bridge-state.py::desired_mcp()` chooses the installed-vs-clone MCP wiring without invoking a real Claude CLI. The gate is wired into `pnpm check` so future decorative closed-schema keys fail before release.
+
+### Verification
+
+- `pnpm check` passes with the new `check-meta-manifest-schema` static guard included.
+- `./run.sh smoke-meta-install-state` passes, proving the state manager/doctor consumers still follow `desired_mcp()` without drift.
+- Installed-location regression probe passes: running `scripts/check-meta-manifest-schema.py` from a synthetic `node_modules/@junghanacs/entwurf` package no longer self-fails.
+- Claude Code 2.1.97 floor validation passed on `hejdev6` after removing the root marketplace `description`; current Claude 2.1.195 validation also passes with warnings only.
+- `LIVE=1 ./run.sh release-gate /tmp/psa-release-gate-0.12.2.NLGhet` passed on 2026-06-29 with `MUST: PASS=17 FAIL=0 SKIP=0` and `BEHAVIOR: PASS=1 FAIL=0`; log `/tmp/entwurf-release-gate-0.12.2-20260629T205339.log`.
+
 ## 0.12.1 — 2026-06-29
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.12.1",
+	"version": "0.12.2",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -118,8 +118,9 @@
 		"typecheck": "tsc --noEmit && tsc -p mcp/tsconfig.json && tsc -p scripts/tsconfig.json",
 		"lint": "biome check .",
 		"format": "biome check --write .",
+		"check-meta-manifest-schema": "./run.sh check-meta-manifest-schema",
 		"check-package-source-routing": "./run.sh check-package-source-routing",
-		"check": "pnpm lint && pnpm typecheck && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-record-v2 && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-meta-dual-read && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-migration && ./run.sh check-meta-dual-consumers && ./run.sh check-meta-capability-source && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh smoke-meta-install-state && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-package-source-routing && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-install-preflight && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-boot && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-v2-spawn && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-spawn-production && ./run.sh check-entwurf-facts && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-entwurf-mailbox-guard && ./run.sh check-auth-boundary && ./run.sh check-acp-provider-surface && ./run.sh check-acp-sdk-surface && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-acp-carrier-augment && ./run.sh check-pack"
+		"check": "pnpm lint && pnpm typecheck && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-record-v2 && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-meta-dual-read && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-migration && ./run.sh check-meta-dual-consumers && ./run.sh check-meta-capability-source && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh smoke-meta-install-state && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-package-source-routing && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-install-preflight && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-boot && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-v2-spawn && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-spawn-production && ./run.sh check-entwurf-facts && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-entwurf-mailbox-guard && ./run.sh check-auth-boundary && ./run.sh check-acp-provider-surface && ./run.sh check-acp-sdk-surface && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-acp-carrier-augment && ./run.sh check-pack"
 	},
 	"pi": {
 		"extensions": [

package/pi/meta-bridge/.claude-plugin/marketplace.json

@@ -1,7 +1,6 @@
 {
 	"name": "meta-bridge-local",
 	"owner": { "name": "junghan0611" },
-	"description": "Local marketplace for the entwurf garden-native meta-bridge. Shipped in-repo (repo-stable, NOT /tmp — an ephemeral source breaks `claude plugin marketplace update`). The installer (./run.sh install-meta-bridge) assembles a self-contained copy under .assembled/ (entry + lib + node-path-baked hooks) and runs `marketplace add` + `install --scope user`.",
 	"plugins": [
 		{
 			"name": "entwurf-meta-receive",

package/run.sh

@@ -93,6 +93,7 @@ Usage:
   ./run.sh smoke-meta-install-state   # 1.0.0 meta-bridge Phase 2: stateful install/uninstall + store-doctor regression gate. Offline/deterministic (deps: bash+node+python3)
   ./run.sh smoke-meta-prune           # 1.0.0 meta-bridge Phase 4: listing-only store janitor regression gate — classify keep/orphan/stale/ambiguous, delete nothing. Offline/deterministic (deps: bash+node)
   ./run.sh smoke-meta-keyset-guard    # 0.10.0 meta-bridge: keyset-owner guard regression — check-keyset-overlap + managed-keys SSOT (disjoint passes, collisions fail). Offline/hermetic (deps: bash+python3)
+  ./run.sh check-meta-manifest-schema # 0.12.2 meta-bridge: CLI-version-INDEPENDENT static guard — plugin manifests pinned to the minimal keyset that validates on the lowest supported Claude (closed-schema regression that broke 0.12.1 install on floor) + desired_mcp installed-vs-clone dual-mode. Offline (deps: python3)
   ./run.sh smoke-claude-native-resume-live # LIVE-only: Claude Code native fresh→--resume continuity + meta-record uniqueness; proves meta-bridge records identity without touching the backend resume path
 
   ./run.sh install-meta-bridge        # 1.0.0 meta-bridge Phase 2: stateful GLOBAL install (plugin + USER MCP + settings keyset, honest uninstall state)
@@ -2803,6 +2804,15 @@ case "$cmd" in
     # Offline/hermetic (deps: bash+python3).
     (cd "$REPO_DIR" && bash scripts/smoke-meta-keyset-guard.sh)
     ;;
+  check-meta-manifest-schema)
+    # 0.12.2 meta-bridge: deterministic, CLI-version-INDEPENDENT guard. `claude plugin
+    # validate` is a CLOSED schema whose allowed keyset differs by version, so a
+    # decorative key (0.12.1's root `description`) passed on the dev box but broke
+    # install on the floor Claude. This pins the committed manifests to the minimal
+    # validated keyset and asserts desired_mcp()'s installed-vs-clone dual-mode.
+    # Offline/hermetic (deps: python3).
+    (cd "$REPO_DIR" && python3 scripts/check-meta-manifest-schema.py)
+    ;;
   smoke-meta-install-state)
     # 1.0.0 meta-bridge Phase 2 regression gate: state file captures pre-install
     # values, install/uninstall touches only the managed keyset, uninstall refuses

package/scripts/check-meta-manifest-schema.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+# check-meta-manifest-schema — deterministic, CLI-version-INDEPENDENT guard for the
+# meta-bridge plugin manifests + the installed-vs-clone MCP wiring decision.
+#
+# Why this exists (0.12.2): `claude plugin validate` is a CLOSED schema — it REJECTS
+# unrecognized keys, and the allowed keyset differs by Claude Code version. 0.12.1
+# shipped a marketplace.json carrying a root `description`; Claude 2.1.195 (the dev
+# box) accepted it, Claude 2.1.97 (the install floor) rejected it with
+# `Unrecognized key: "description"`, so `entwurf install-meta-bridge` died on the
+# floor host while the release looked green. The lesson: a "nice to have" decorative
+# key in a closed-schema manifest is a future regression surface. This guard pins the
+# committed manifests to the MINIMAL keyset confirmed to validate on the lowest
+# supported Claude, independent of whatever CLI version happens to run here.
+#
+# It also asserts meta-bridge-state.py::desired_mcp() picks the stable `entwurf-bridge`
+# bin for an installed package and the clone's start.sh for a dev clone (the other
+# 0.12.1 install-surface fragility: baking the pnpm store path goes stale on peer bumps).
+#
+# Offline / hermetic. Deps: python3 only.
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+REPO = HERE.parent
+MB = REPO / "pi" / "meta-bridge"
+STATE = HERE / "meta-bridge-state.py"
+
+fail = 0
+
+
+def ok(msg: str) -> None:
+    print(f"  ok    {msg}")
+
+
+def bad(msg: str) -> None:
+    global fail
+    print(f"  FAIL  {msg}")
+    fail = 1
+
+
+def load(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        bad(f"cannot parse {path}: {exc}")
+        return None
+
+
+def subset(label: str, got, allowed: set[str]) -> None:
+    if not isinstance(got, dict):
+        bad(f"{label}: expected an object, got {type(got).__name__}")
+        return
+    extra = set(got) - allowed
+    if extra:
+        bad(f"{label}: keys {sorted(extra)} outside minimal allowed set {sorted(allowed)} "
+            f"(closed-schema risk: an older Claude may reject them)")
+    else:
+        ok(f"{label}: keys ⊆ {sorted(allowed)}")
+
+
+# --- marketplace.json --------------------------------------------------------
+mkt = load(MB / ".claude-plugin" / "marketplace.json")
+if mkt is not None:
+    subset("marketplace root", mkt, {"name", "owner", "plugins"})
+    subset("marketplace.owner", mkt.get("owner", {}), {"name"})
+    plugins = mkt.get("plugins")
+    if not isinstance(plugins, list) or not plugins:
+        bad("marketplace.plugins must be a non-empty array")
+    else:
+        for i, p in enumerate(plugins):
+            subset(f"marketplace.plugins[{i}]", p, {"name", "source", "description"})
+
+# --- plugin.json -------------------------------------------------------------
+plug = load(MB / "entwurf-meta-receive" / ".claude-plugin" / "plugin.json")
+if plug is not None:
+    subset("plugin.json", plug, {"name", "version", "description"})
+
+# --- hooks.json --------------------------------------------------------------
+hooks = load(MB / "entwurf-meta-receive" / "hooks" / "hooks.json")
+if hooks is not None:
+    subset("hooks.json root", hooks, {"hooks"})
+    # Pin the hook EVENT names too — an unrecognized event key is the same closed-schema
+    # risk as an unrecognized field. These four are the meta-bridge's load-bearing events.
+    subset("hooks.json events", hooks.get("hooks") or {},
+           {"SessionStart", "CwdChanged", "UserPromptSubmit", "FileChanged"})
+    for event, entries in (hooks.get("hooks") or {}).items():
+        if not isinstance(entries, list):
+            bad(f"hooks.{event} must be an array")
+            continue
+        for j, entry in enumerate(entries):
+            subset(f"hooks.{event}[{j}]", entry, {"matcher", "hooks"})
+            for k, h in enumerate(entry.get("hooks", []) if isinstance(entry, dict) else []):
+                # asyncRewake/timeout are load-bearing on the FileChanged doorbell —
+                # allowed, NOT decorative. Anything beyond this set must be reviewed.
+                subset(f"hooks.{event}[{j}].hooks[{k}]", h, {"type", "command", "asyncRewake", "timeout"})
+
+# --- desired_mcp() installed-vs-clone dual-mode ------------------------------
+def desired_mcp(repo: str):
+    out = subprocess.run(
+        [sys.executable, str(STATE), "desired-mcp", "--repo", repo],
+        capture_output=True, text=True,
+    )
+    if out.returncode != 0:
+        bad(f"desired-mcp --repo {repo} exited {out.returncode}: {out.stderr.strip()}")
+        return None
+    return json.loads(out.stdout)
+
+
+# Both probes use SYNTHETIC paths that need not exist — never REPO. If this guard ran
+# from an installed package (e.g. `entwurf check-meta-manifest-schema`), REPO would
+# itself end in node_modules/@junghanacs/entwurf and a REPO-based clone probe would
+# wrongly resolve to the installed shape and self-fail. Fixed, installed-vs-clone-shaped
+# literals make the assertion location-independent.
+installed = desired_mcp("/opt/x/node_modules/@junghanacs/entwurf")
+if installed is not None:
+    if installed.get("command") == "entwurf-bridge" and installed.get("args") == []:
+        ok("desired_mcp(installed-shaped) → stable `entwurf-bridge` bin (no store path baked)")
+    else:
+        bad(f"desired_mcp(installed-shaped) should wire the `entwurf-bridge` bin, got {installed.get('command')} {installed.get('args')}")
+
+clone = desired_mcp("/opt/entwurf-dev-clone")
+if clone is not None:
+    args = clone.get("args") or [""]
+    if clone.get("command") == "bash" and str(args[0]).endswith("mcp/entwurf-bridge/start.sh"):
+        ok("desired_mcp(clone-shaped) → that clone's start.sh (not the global bin)")
+    else:
+        bad(f"desired_mcp(clone-shaped) should wire bash start.sh, got {clone.get('command')} {args}")
+
+# both modes must keep the canonical sender env
+for label, entry in (("installed", installed), ("clone", clone)):
+    if entry is None:
+        continue
+    env = entry.get("env", {})
+    if env.get("ENTWURF_BRIDGE_REQUIRE_META_SENDER") == "1" and \
+       env.get("ENTWURF_BRIDGE_EXTERNAL_AGENT_ID") == "external-mcp/claude-code":
+        ok(f"desired_mcp({label}) carries canonical sender env")
+    else:
+        bad(f"desired_mcp({label}) dropped canonical sender env: {env}")
+
+if fail:
+    print("check-meta-manifest-schema FAIL")
+    sys.exit(1)
+print("check-meta-manifest-schema PASS")

package/scripts/meta-bridge-install.sh

@@ -115,9 +115,23 @@ claude mcp remove entwurf-bridge -s user >/dev/null 2>&1 || true
 # 0.11 S2 cutover: drop any stale USER-scope pi-tools-bridge entry written by a
 # prior version (one-shot rename cleanup, not a runtime alias).
 claude mcp remove pi-tools-bridge -s user >/dev/null 2>&1 || true
-claude mcp add -s user entwurf-bridge \
-  -e ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code \
-  -- bash "$REPO/mcp/entwurf-bridge/start.sh" >/dev/null
+# 0.12.2 installed-vs-clone dual-mode — MUST mirror meta-bridge-state.py::desired_mcp(),
+# which the trailing `apply` re-asserts as the SSOT. An installed package ($REPO ends
+# in node_modules/@junghanacs/entwurf) wires the STABLE `entwurf-bridge` bin shim; baking
+# the pnpm store path here would go stale on any peer/version bump. A dev clone pins to
+# this clone's start.sh. Both branches carry the same two env vars desired_mcp() writes.
+case "$REPO" in
+  */node_modules/@junghanacs/entwurf)
+    claude mcp add -s user entwurf-bridge \
+      -e ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code \
+      -e ENTWURF_BRIDGE_REQUIRE_META_SENDER=1 \
+      -- entwurf-bridge >/dev/null ;;
+  *)
+    claude mcp add -s user entwurf-bridge \
+      -e ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code \
+      -e ENTWURF_BRIDGE_REQUIRE_META_SENDER=1 \
+      -- bash "$REPO/mcp/entwurf-bridge/start.sh" >/dev/null ;;
+esac
 (cd /tmp && claude mcp get entwurf-bridge 2>/dev/null | grep -q "Scope: User config") || \
   die "post-install: entwurf-bridge is not reachable as USER-scope MCP from /tmp"
 echo "[meta-bridge-install] installed entwurf-bridge MCP (scope: user = global receiver tools)"

package/scripts/meta-bridge-state.py

@@ -264,20 +264,42 @@ def desired_marketplace(asm: Path) -> dict[str, Any]:
     return {"source": {"source": "directory", "path": str(asm.resolve())}}
 
 
+def is_installed_package(repo: Path) -> bool:
+    # An installed (npm / pnpm) layout always ends in node_modules/@junghanacs/entwurf
+    # (pnpm global nests it under .pnpm/<hash>/node_modules/@junghanacs/entwurf). A dev
+    # clone never lives under node_modules/@junghanacs/entwurf, so the trailing three
+    # path components cleanly distinguish the two WITHOUT a PATH lookup (`command -v
+    # entwurf-bridge` could resolve a stale GLOBAL bin from a clone host and is wrong here).
+    parts = repo.resolve().parts
+    return parts[-3:] == ("node_modules", "@junghanacs", "entwurf")
+
+
 def desired_mcp(repo: Path) -> dict[str, Any]:
+    env = {
+        "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID": "external-mcp/claude-code",
+        # Anonymous sends are forbidden on the Claude Code install path: a send
+        # with no pi-session identity AND no meta-sender marker is refused, not
+        # delivered as an unidentified external. The SessionStart hook writes
+        # the marker (parent-pid keyed), so a normally-opened session always has
+        # an authoritative garden-id sender.
+        "ENTWURF_BRIDGE_REQUIRE_META_SENDER": "1",
+    }
+    if is_installed_package(repo):
+        # Installed package: wire the STABLE `entwurf-bridge` bin shim that npm/pnpm
+        # place on PATH. Baking repo/mcp/entwurf-bridge/start.sh would embed the pnpm
+        # store path (.pnpm/@junghanacs+entwurf@<ver>_<peer-hash>/...), which moves
+        # on any peer/version change and leaves a dead MCP command. The bare bin name
+        # tracks whatever version is currently installed — the right behaviour for a
+        # managed install host. start.sh's own position-based dual-mode then runs the
+        # dist boot under node_modules. (0.12.2 fix; 0.12.1 shipped only the clone path.)
+        return {"type": "stdio", "command": "entwurf-bridge", "args": [], "env": env}
+    # Dev clone: pin to THIS clone's launcher (an absolute resolved path), never the
+    # global bin, so a clone host stays bound to its own source tree.
     return {
         "type": "stdio",
         "command": "bash",
         "args": [str((repo / "mcp" / "entwurf-bridge" / "start.sh").resolve())],
-        "env": {
-            "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID": "external-mcp/claude-code",
-            # Anonymous sends are forbidden on the Claude Code install path: a send
-            # with no pi-session identity AND no meta-sender marker is refused, not
-            # delivered as an unidentified external. The SessionStart hook writes
-            # the marker (parent-pid keyed), so a normally-opened session always has
-            # an authoritative garden-id sender.
-            "ENTWURF_BRIDGE_REQUIRE_META_SENDER": "1",
-        },
+        "env": env,
     }
 
 
@@ -519,7 +541,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(description="entwurf meta-bridge state manager")
     parser.add_argument(
         "command",
-        choices=["prepare", "apply", "preflight-uninstall", "uninstall", "check", "managed-keys"],
+        choices=["prepare", "apply", "preflight-uninstall", "uninstall", "check", "managed-keys", "desired-mcp"],
     )
     parser.add_argument("--repo", default=Path(__file__).resolve().parents[1], type=Path)
     parser.add_argument("--asm", default=None, type=Path)
@@ -539,6 +561,11 @@ def main() -> int:
             check(repo, asm)
         elif args.command == "managed-keys":
             print(json.dumps(managed_keys(), indent=2))
+        elif args.command == "desired-mcp":
+            # Debug/guard surface: print the user-scope MCP entry desired_mcp() would
+            # write for --repo. Lets a deterministic guard assert the installed-vs-clone
+            # dual-mode without spinning up a real `claude` CLI. --repo need not exist.
+            print(json.dumps(desired_mcp(repo), indent=2))
     except StateError as exc:
         print(f"meta-bridge-state: {exc}", file=sys.stderr)
         return 1