claude-multiacc 2.0.38 → 2.0.40

package/lib/mcp_registry.py

@@ -0,0 +1,1372 @@
+#!/usr/bin/env python3
+"""Pool-level MCP server registry: one document, reconciled into every account.
+
+WHY (2026-09-22). Claude Code and Codex keep their MCP servers inside the config
+dir — `<CLAUDE_CONFIG_DIR>/.claude.json` (user scope, plus a per-project entry
+under `projects[<cwd>]`) and `<CODEX_HOME>/config.toml` (`[mcp_servers.<name>]`).
+Under the pool every launch runs in a different config dir, so a stock
+`claude mcp add` (or `npx appinspire-mcp install`) lands in ONE random account:
+the next session, picked on another account, has no such server, and the one
+after that connects an older copy somebody registered months ago. That is how
+`appinspire-mcp` was "not connecting in every session".
+
+The fix is one registry per pool root that is authoritative for the servers it
+names and is reconciled into every account dir:
+
+  ROOT/mcp-servers.json        the operator's registry — SYNCED to the server and
+                               every manifest peer like the manifest itself
+  ROOT/mcp-servers.local.json  a machine-local overlay other software on this
+                               machine (app-robot's runner) publishes into, never
+                               synced; the synced registry wins on any conflict.
+                               A REPLICA pool (sync-role = replica) also keeps its
+                               own adds/removes/learned changes here, under the
+                               owner `local`: the source's next push would
+                               overwrite its registry, but never this file.
+  <acct>/.mcp-applied          a one-line stamp of what the last reconcile saw,
+                               so the shims can skip python when nothing moved
+
+Reconcile rules, the same for both providers:
+  * every registry server is upserted into the account under its own name;
+  * a name in `retired` (the tombstone an explicit `mcp remove` leaves behind)
+    is deleted EVERYWHERE — user scope and every project entry — even if the
+    registry never managed it, which is what "we do not use adspower-local-api
+    any more" needs to hold fleet-wide; a name in `retiredUser` (a learned stock
+    `claude mcp remove -s user`, or `mcp remove --user-only`) leaves project
+    entries alone, exactly as the client itself did;
+  * anything else the account holds is left alone (an account may carry its own
+    extras);
+  * project-scoped entries (`projects` in the registry) exist for claude only:
+    Codex 0.156 reads no per-project config at all.
+
+Both providers speak the same block shape — Claude Code's own (`type`, `command`,
+`args`, `env` / `url`, `headers`) — and the codex side is a translation of it
+(`KEY=${KEY}` env references become `env_vars`, headers become `http_headers` /
+`env_http_headers` / `bearer_token_env_var`, a stdio server gets
+`startup_timeout_sec` 60 so a cold `npx` download does not trip codex's 10 s
+default). Codex-only keys ride along in the registry (`startup_timeout_sec`,
+`env_vars`, … and a `codex` passthrough dict for anything else codex wrote, such
+as an `oauth` sub-table) and are stripped for claude.
+
+The claude path runs on stock macOS python (3.9). The codex path needs tomllib
+(3.11+) and re-executes itself on an installed newer interpreter through
+lib/codex_python.py — the same rule codex_settings.py already lives by.
+
+Exit codes: 0 done; 1 refused (nothing saved); 2 usage; 3 the registry WAS saved
+but some account failed to reconcile (details on stderr, `apply` repairs it).
+"""
+from __future__ import annotations
+
+import argparse
+import copy
+import datetime as _dt
+import json
+import math
+import os
+import re
+import shlex
+import sys
+import tempfile
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+REGISTRY_FILE = "mcp-servers.json"
+OVERLAY_FILE = "mcp-servers.local.json"
+STAMP_FILE = ".mcp-applied"
+LOCK_DIR = os.path.join(".locks", "mcp")
+PROVIDERS = ("claude", "codex")
+CONFIG_FILE = {"claude": ".claude.json", "codex": "config.toml"}
+TRANSPORTS = ("stdio", "http", "sse", "ws")
+#: Keys a codex block may carry that Claude Code must never see in .claude.json.
+CODEX_ONLY_KEYS = frozenset({"startup_timeout_sec", "tool_timeout_sec", "env_vars",
+                             "enabled", "cwd", "http_headers", "env_http_headers",
+                             "bearer_token_env_var", "codex"})
+#: The codex table keys this module models; everything else codex writes round-trips
+#: through the block's `codex` passthrough dict untouched.
+CODEX_MODELLED_KEYS = frozenset({"command", "args", "env", "env_vars", "url", "http_headers",
+                                 "env_http_headers", "bearer_token_env_var",
+                                 "startup_timeout_sec", "tool_timeout_sec", "cwd", "enabled"})
+#: A cold `npx -y <pkg>` resolves and downloads before the server answers
+#: `initialize`; codex gives a server 10 s by default and then reports it dead
+#: for the whole session. Claude Code waits longer on its own.
+DEFAULT_STARTUP_TIMEOUT = 60
+MAX_TIMEOUT = 86400
+ENV_REF = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)(:-[^}]*)?\}$")
+BEARER_REF = re.compile(r"^Bearer \$\{([A-Za-z_][A-Za-z0-9_]*)\}$")
+ACCT_ID = re.compile(r"^acct-\d{2,4}$")
+BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+#: Claude Code's own rule for a server name (`claude mcp add` refuses anything else).
+STRICT_NAME = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+#: The keys Claude Code creates for a project entry the first time a session
+#: opens that directory. A registry-created entry carries the same skeleton so
+#: the client finds every field it expects.
+PROJECT_SKELETON = {
+    "allowedTools": [], "mcpContextUris": [], "mcpServers": {},
+    "enabledMcpjsonServers": [], "disabledMcpjsonServers": [],
+    "hasTrustDialogAccepted": False, "hasClaudeMdExternalIncludesApproved": False,
+    "hasClaudeMdExternalIncludesWarningShown": False,
+}
+EXIT_PARTIAL = 3
+
+
+class RegistryError(Exception):
+    """A refusal that reaches the operator as `mcp-registry: <message>`."""
+
+
+def _warn(message):
+    print(f"mcp-registry: {message}", file=sys.stderr)
+
+
+# --------------------------------------------------------------------------- io
+
+def _now_iso():
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _read_json(path, default):
+    try:
+        with open(path, encoding="utf-8") as handle:
+            data = json.load(handle)
+    except FileNotFoundError:
+        return copy.deepcopy(default)
+    except (OSError, ValueError) as exc:
+        raise RegistryError(f"{path} is not readable JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise RegistryError(f"{path} does not hold a JSON object")
+    return data
+
+
+def _atomic_write(path, text, default_mode=0o600):
+    directory = os.path.dirname(path) or "."
+    os.makedirs(directory, exist_ok=True)
+    try:
+        mode = os.stat(path).st_mode & 0o777
+    except FileNotFoundError:
+        mode = default_mode
+    handle, scratch = tempfile.mkstemp(prefix=".mcp-registry-", dir=directory)
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            os.fchmod(stream.fileno(), mode)
+            stream.write(text)
+        os.replace(scratch, path)
+    except BaseException:
+        try:
+            os.unlink(scratch)
+        except OSError:
+            pass
+        raise
+
+
+def _log(root, message):
+    try:
+        with open(os.path.join(root, "ops.log"), "a", encoding="utf-8") as handle:
+            handle.write(f"{_now_iso()} mcp {message}\n")
+    except OSError:
+        pass
+
+
+class _Lock:
+    """mkdir lock, the same shape as lib/common.sh mutate_lock (30 s stale)."""
+
+    def __init__(self, root):
+        self.path = os.path.join(root, LOCK_DIR)
+        self.held = False
+
+    def __enter__(self):
+        os.makedirs(os.path.dirname(self.path), exist_ok=True)
+        deadline = time.time() + 60
+        while True:
+            try:
+                os.mkdir(self.path)
+                self.held = True
+                return self
+            except FileExistsError:
+                try:
+                    if time.time() - os.stat(self.path).st_mtime > 30:
+                        os.rmdir(self.path)
+                        continue
+                except OSError:
+                    pass
+                if time.time() > deadline:
+                    raise RegistryError("could not take the registry lock; try again")
+                time.sleep(0.1)
+
+    def __exit__(self, *_exc):
+        if self.held:
+            try:
+                os.rmdir(self.path)
+            except OSError:
+                pass
+            self.held = False
+
+
+# ------------------------------------------------------------ documents
+
+def _normalize_section(section):
+    """Every server section — the registry, an overlay owner — has the same shape."""
+    if not isinstance(section, dict):
+        section = {}
+    if not isinstance(section.get("mcpServers"), dict):
+        section["mcpServers"] = {}
+    for key in ("retired", "retiredUser"):
+        if not isinstance(section.get(key), list):
+            section[key] = []
+        section[key] = [str(name) for name in section[key]]
+    if not isinstance(section.get("projects"), dict):
+        section["projects"] = {}
+    for path, entry in list(section["projects"].items()):
+        if not isinstance(entry, dict):
+            section["projects"][path] = entry = {}
+        if not isinstance(entry.get("mcpServers"), dict):
+            entry["mcpServers"] = {}
+        if not isinstance(entry.get("retired"), list):
+            entry["retired"] = []
+        if "enabledMcpjsonServers" in entry and not isinstance(entry["enabledMcpjsonServers"], list):
+            entry.pop("enabledMcpjsonServers")
+    return section
+
+
+def _empty_registry():
+    return {"version": 1, "mcpServers": {}, "retired": [], "retiredUser": [], "projects": {}}
+
+
+def load_registry(root):
+    doc = _normalize_section(_read_json(os.path.join(root, REGISTRY_FILE), _empty_registry()))
+    doc.setdefault("version", 1)
+    return doc
+
+
+def save_registry(root, doc):
+    doc["version"] = 1
+    doc["updated_at"] = _now_iso()
+    _atomic_write(os.path.join(root, REGISTRY_FILE), json.dumps(doc, indent=2) + "\n", 0o644)
+
+
+def load_overlay(root):
+    doc = _read_json(os.path.join(root, OVERLAY_FILE), {"version": 1, "owners": {}})
+    if not isinstance(doc.get("owners"), dict):
+        doc["owners"] = {}
+    for owner in list(doc["owners"]):
+        doc["owners"][owner] = _normalize_section(doc["owners"][owner])
+    return doc
+
+
+def save_overlay(root, doc):
+    doc["version"] = 1
+    doc["updated_at"] = _now_iso()
+    _atomic_write(os.path.join(root, OVERLAY_FILE), json.dumps(doc, indent=2) + "\n", 0o644)
+
+
+def is_replica(root):
+    """A pool the source machine pushes to: its registry is the source's copy."""
+    try:
+        with open(os.path.join(root, "sync-role"), encoding="utf-8") as handle:
+            return handle.read().strip().lower() == "replica"
+    except OSError:
+        return False
+
+
+class Effective:
+    """What every account must hold and what it must not, merged from all sections."""
+
+    def __init__(self):
+        self.servers = {}
+        self.retired = set()          # everywhere
+        self.retired_user = set()     # user scope only
+        self.projects = {}
+
+    def _merge_projects(self, projects):
+        for path, entry in projects.items():
+            target = self.projects.setdefault(path, {"mcpServers": {}, "retired": [],
+                                                     "enabledMcpjsonServers": []})
+            for name, block in (entry.get("mcpServers") or {}).items():
+                if isinstance(block, dict):
+                    target["mcpServers"][str(name)] = block
+                    target["retired"] = [n for n in target["retired"] if n != name]
+            for name in entry.get("retired") or []:
+                target["mcpServers"].pop(name, None)
+                if name not in target["retired"]:
+                    target["retired"].append(name)
+            for name in entry.get("enabledMcpjsonServers") or []:
+                if name not in target["enabledMcpjsonServers"]:
+                    target["enabledMcpjsonServers"].append(name)
+
+    def _apply_section(self, section):
+        gone = set(section["retired"])
+        gone_user = set(section["retiredUser"])
+        for name, block in section["mcpServers"].items():
+            if isinstance(block, dict) and name not in gone and name not in gone_user:
+                self.servers[str(name)] = block
+                self.retired.discard(name)
+                self.retired_user.discard(name)
+        for name in gone:
+            self.servers.pop(name, None)
+            self.retired.add(name)
+            self.retired_user.discard(name)
+        for name in gone_user:
+            self.servers.pop(name, None)
+            if name not in self.retired:
+                self.retired_user.add(name)
+        self._merge_projects(section["projects"])
+
+
+def effective(registry, overlay):
+    """Overlay owners first (alphabetically, a later owner wins a clash, a tombstone
+    beats a server inside one owner); the synced registry has the final word both
+    ways: its servers survive any overlay tombstone and its tombstones remove any
+    overlay server."""
+    result = Effective()
+    for owner in sorted(overlay.get("owners", {})):
+        result._apply_section(overlay["owners"][owner])
+    result._apply_section(registry)
+    return result
+
+
+# ------------------------------------------------------------- validation
+
+def _validate_name(name, strict=True):
+    name = str(name)
+    if strict:
+        if not STRICT_NAME.match(name):
+            raise RegistryError(f"not a usable MCP server name: {name!r} "
+                                "(letters, digits, '_' and '-', up to 128 characters)")
+        return name
+    if not name or name in (".", "..") or len(name) > 128 or re.search(r"[\s/\\]", name):
+        raise RegistryError(f"not a usable MCP server name: {name!r}")
+    return name
+
+
+def _scalar(value):
+    return isinstance(value, (str, int, float)) and not isinstance(value, bool)
+
+
+def _number_ok(value, lo=0, hi=MAX_TIMEOUT):
+    return (isinstance(value, (int, float)) and not isinstance(value, bool)
+            and math.isfinite(value) and lo <= value <= hi)
+
+
+def validate_block(name, block):
+    """The block shape both clients can consume; raises RegistryError otherwise."""
+    if not isinstance(block, dict):
+        raise RegistryError(f"{name}: the server block must be a JSON object")
+    kind = block.get("type")
+    if kind is not None and kind not in TRANSPORTS:
+        raise RegistryError(f"{name}: unknown transport {kind!r} (stdio, http, sse, ws)")
+    command, url = block.get("command"), block.get("url")
+    if not ((isinstance(command, str) and command) or (isinstance(url, str) and url)):
+        raise RegistryError(f"{name}: needs a non-empty \"command\" or \"url\"")
+    if command is not None and not isinstance(command, str):
+        raise RegistryError(f"{name}: \"command\" must be a string")
+    if url is not None and not isinstance(url, str):
+        raise RegistryError(f"{name}: \"url\" must be a string")
+    args = block.get("args")
+    if args is not None and (not isinstance(args, list) or not all(_scalar(a) for a in args)):
+        raise RegistryError(f"{name}: \"args\" must be a list of strings")
+    for key in ("env", "headers", "http_headers", "env_http_headers"):
+        value = block.get(key)
+        if value is not None and (not isinstance(value, dict)
+                                  or not all(_scalar(v) for v in value.values())):
+            raise RegistryError(f"{name}: \"{key}\" must be an object of string values")
+    env_vars = block.get("env_vars")
+    if env_vars is not None and (not isinstance(env_vars, list)
+                                 or not all(isinstance(v, str) for v in env_vars)):
+        raise RegistryError(f"{name}: \"env_vars\" must be a list of variable names")
+    for key in ("startup_timeout_sec", "tool_timeout_sec"):
+        if key in block and not _number_ok(block[key]):
+            raise RegistryError(f"{name}: \"{key}\" must be a number of seconds "
+                                f"between 0 and {MAX_TIMEOUT}")
+    if "enabled" in block and not isinstance(block["enabled"], bool):
+        raise RegistryError(f"{name}: \"enabled\" must be true or false")
+    for key in ("cwd", "bearer_token_env_var"):
+        if key in block and (not isinstance(block[key], str) or not block[key]):
+            raise RegistryError(f"{name}: \"{key}\" must be a non-empty string")
+    if "codex" in block and not isinstance(block["codex"], dict):
+        raise RegistryError(f"{name}: \"codex\" must be an object")
+    return block
+
+
+# ------------------------------------------------------------------ accounts
+
+def manifest_account_dirs(root):
+    manifest = os.path.join(root, "accounts.json")
+    try:
+        with open(manifest, encoding="utf-8") as handle:
+            doc = json.load(handle)
+    except FileNotFoundError:
+        return []
+    except (OSError, ValueError) as exc:
+        raise RegistryError(f"{manifest} is not readable JSON: {exc}") from exc
+    dirs = []
+    for account in doc.get("accounts") or []:
+        account_id = account.get("id", "") if isinstance(account, dict) else ""
+        if isinstance(account_id, str) and ACCT_ID.match(account_id):
+            path = os.path.join(root, account_id)
+            if os.path.isdir(path):
+                dirs.append(path)
+    return dirs
+
+
+def _sig_part(path):
+    try:
+        st = os.stat(path)
+    except OSError:
+        return "-"
+    return f"{int(st.st_mtime)}:{st.st_size}"
+
+
+def stamp_signature(root, provider, account_dir):
+    return ",".join(_sig_part(path) for path in (
+        os.path.join(root, REGISTRY_FILE), os.path.join(root, OVERLAY_FILE),
+        os.path.join(account_dir, CONFIG_FILE[provider])))
+
+
+def write_stamp(root, provider, account_dir):
+    try:
+        _atomic_write(os.path.join(account_dir, STAMP_FILE),
+                      stamp_signature(root, provider, account_dir) + "\n")
+    except OSError:
+        pass
+
+
+# --------------------------------------------------------------- claude side
+
+def _kind_of(block):
+    kind = block.get("type")
+    if kind in TRANSPORTS:
+        return kind
+    return "stdio" if block.get("command") else ("http" if block.get("url") else "stdio")
+
+
+def claude_block(block):
+    """Claude Code's own shape, codex-only keys dropped."""
+    validate_block(block.get("__name__", "server"), block)
+    out = {key: copy.deepcopy(value) for key, value in block.items()
+           if key not in CODEX_ONLY_KEYS and key != "__name__"}
+    kind = _kind_of(out)
+    ordered = {"type": kind}
+    if kind == "stdio":
+        ordered["command"] = str(out.get("command", ""))
+        ordered["args"] = [str(arg) for arg in (out.get("args") or [])]
+        env = out.get("env") or {}
+        ordered["env"] = {str(k): str(v) for k, v in env.items()}
+    else:
+        ordered["url"] = str(out.get("url", ""))
+        headers = out.get("headers")
+        if isinstance(headers, dict) and headers:
+            ordered["headers"] = {str(k): str(v) for k, v in headers.items()}
+    for key, value in out.items():
+        if key not in ordered:
+            ordered[key] = value
+    return ordered
+
+
+def _claude_load(account_dir):
+    path = os.path.join(account_dir, CONFIG_FILE["claude"])
+    try:
+        with open(path, encoding="utf-8") as handle:
+            doc = json.load(handle)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError) as exc:
+        raise RegistryError(f"{path} is not readable JSON: {exc}") from exc
+    if not isinstance(doc, dict):
+        raise RegistryError(f"{path} does not hold a JSON object")
+    return doc
+
+
+def _claude_save(account_dir, doc):
+    _atomic_write(os.path.join(account_dir, CONFIG_FILE["claude"]),
+                  json.dumps(doc, indent=2) + "\n")
+
+
+def _project_entry(doc, path):
+    projects = doc.setdefault("projects", {})
+    if not isinstance(projects, dict):
+        projects = doc["projects"] = {}
+    entry = projects.get(path)
+    if not isinstance(entry, dict):
+        entry = projects[path] = copy.deepcopy(PROJECT_SKELETON)
+    if not isinstance(entry.get("mcpServers"), dict):
+        entry["mcpServers"] = {}
+    return entry
+
+
+def reconcile_claude(doc, eff):
+    """Return (reconciled document, notes). Compare to the input to know if it changed."""
+    doc = copy.deepcopy(doc)
+    notes = []
+    user = doc.get("mcpServers")
+    if not isinstance(user, dict):
+        user = doc["mcpServers"] = {}
+    for name, block in eff.servers.items():
+        try:
+            user[name] = claude_block(dict(block, __name__=name))
+        except RegistryError as exc:
+            notes.append(f"{exc} — skipped")
+    for name in eff.retired | eff.retired_user:
+        user.pop(name, None)
+    existing_projects = doc.get("projects")
+    if isinstance(existing_projects, dict) and eff.retired:
+        for entry in existing_projects.values():
+            if isinstance(entry, dict) and isinstance(entry.get("mcpServers"), dict):
+                for name in eff.retired:
+                    entry["mcpServers"].pop(name, None)
+    for path, spec in eff.projects.items():
+        wanted = spec.get("mcpServers") or {}
+        gone = set(spec.get("retired") or []) | eff.retired
+        enabled = spec.get("enabledMcpjsonServers") or []
+        if not wanted and not (spec.get("retired") or []) and not enabled:
+            continue
+        entry = _project_entry(doc, path)
+        for name, block in wanted.items():
+            if name in eff.retired:
+                continue
+            try:
+                entry["mcpServers"][name] = claude_block(dict(block, __name__=name))
+            except RegistryError as exc:
+                notes.append(f"{exc} — skipped")
+        for name in gone:
+            entry["mcpServers"].pop(name, None)
+        if enabled:
+            current = entry.get("enabledMcpjsonServers")
+            current = list(current) if isinstance(current, list) else []
+            for name in enabled:
+                if name not in current:
+                    current.append(name)
+            entry["enabledMcpjsonServers"] = current
+            disabled = entry.get("disabledMcpjsonServers")
+            if isinstance(disabled, list):
+                entry["disabledMcpjsonServers"] = [n for n in disabled if n not in enabled]
+    return doc, notes
+
+
+def apply_claude(account_dir, eff):
+    before = _claude_load(account_dir)
+    after, notes = reconcile_claude(before, eff)
+    for note in notes:
+        _warn(f"{os.path.basename(account_dir.rstrip('/'))}: {note}")
+    if after == before and os.path.exists(os.path.join(account_dir, CONFIG_FILE["claude"])):
+        return "unchanged"
+    _claude_save(account_dir, after)
+    return "updated"
+
+
+def snapshot_claude(account_dir):
+    doc = _claude_load(account_dir)
+    user = doc.get("mcpServers") if isinstance(doc.get("mcpServers"), dict) else {}
+    projects = {}
+    for path, entry in (doc.get("projects") or {}).items():
+        if not isinstance(entry, dict):
+            continue
+        mcp = entry.get("mcpServers") if isinstance(entry.get("mcpServers"), dict) else {}
+        enabled = entry.get("enabledMcpjsonServers")
+        disabled = entry.get("disabledMcpjsonServers")
+        projects[path] = {
+            "mcpServers": mcp,
+            "enabledMcpjsonServers": list(enabled) if isinstance(enabled, list) else [],
+            "disabledMcpjsonServers": list(disabled) if isinstance(disabled, list) else [],
+        }
+    return {"provider": "claude", "user": user, "projects": projects}
+
+
+# ---------------------------------------------------------------- codex side
+
+def _tomllib():
+    try:
+        import tomllib  # noqa: WPS433 — 3.11+ only, hence the lazy import
+    except ImportError:
+        raise RegistryError("the codex registry needs Python 3.11+ (tomllib); "
+                            "install a newer python3 (brew install python)") from None
+    return tomllib
+
+
+def codex_block(name, block):
+    """Translate a Claude-shaped block into the keys codex's config.toml takes.
+
+    Returns (table, notes). A None table means "not expressible" (an SSE or
+    WebSocket transport): the caller skips the server rather than writing
+    something codex would refuse to start. `notes` lists what had to be left out.
+    """
+    validate_block(name, block)
+    notes = []
+    kind = _kind_of(block)
+    if kind not in ("stdio", "http"):
+        return None, [f"{name} uses a transport codex cannot express ({kind}) — skipped"]
+    out = {}
+    if kind == "stdio":
+        out["command"] = str(block.get("command", ""))
+        out["args"] = [str(arg) for arg in (block.get("args") or [])]
+        env, env_vars = {}, []
+        for key, value in (block.get("env") or {}).items():
+            key, value = str(key), str(value)
+            reference = ENV_REF.match(value)
+            if not reference:
+                env[key] = value
+            elif reference.group(1) == key and not reference.group(2):
+                # codex forwards a variable under its own name and expands nothing
+                # else, so only KEY=${KEY} survives the translation.
+                env_vars.append(key)
+            else:
+                notes.append(f"{name}: env {key}={value} cannot be expressed for codex "
+                             "(it forwards a variable only under its own name, with no "
+                             "default) — that variable is left out of the codex server")
+        for var in block.get("env_vars") or []:
+            if var not in env_vars:
+                env_vars.append(str(var))
+        if env:
+            out["env"] = env
+        if env_vars:
+            out["env_vars"] = env_vars
+        out["startup_timeout_sec"] = block.get("startup_timeout_sec", DEFAULT_STARTUP_TIMEOUT)
+    else:
+        out["url"] = str(block.get("url", ""))
+        headers, env_headers, bearer = {}, {}, None
+        for key, value in (block.get("headers") or {}).items():
+            key, value = str(key), str(value)
+            bearer_ref = BEARER_REF.match(value)
+            if bearer_ref and key.lower() == "authorization":
+                bearer = bearer_ref.group(1)
+                continue
+            reference = ENV_REF.match(value)
+            if reference and not reference.group(2):
+                env_headers[key] = reference.group(1)
+            elif reference:
+                notes.append(f"{name}: header {key}={value} carries a default codex cannot "
+                             "express — header left out of the codex server")
+            else:
+                headers[key] = value
+        for key, source in (("http_headers", headers), ("env_http_headers", env_headers)):
+            explicit = block.get(key)
+            if isinstance(explicit, dict):
+                source.update({str(k): str(v) for k, v in explicit.items()})
+            if source:
+                out[key] = source
+        bearer = block.get("bearer_token_env_var") or bearer
+        if bearer:
+            out["bearer_token_env_var"] = str(bearer)
+        if "startup_timeout_sec" in block:
+            out["startup_timeout_sec"] = block["startup_timeout_sec"]
+    for key in ("tool_timeout_sec", "cwd", "enabled"):
+        if key in block:
+            out[key] = block[key]
+    for key, value in (block.get("codex") or {}).items():
+        if key not in out:
+            out[str(key)] = copy.deepcopy(value)
+    return out, notes
+
+
+def codex_to_claude(name, table):
+    """The registry (Claude-shaped) block for a table read from codex's config."""
+    block = {}
+    if table.get("command"):
+        block["type"] = "stdio"
+        block["command"] = str(table["command"])
+        args = table.get("args") or []
+        block["args"] = [str(arg) for arg in (args if isinstance(args, list) else [args])]
+        env = {str(k): str(v) for k, v in (table.get("env") or {}).items()} \
+            if isinstance(table.get("env"), dict) else {}
+        env_vars = table.get("env_vars") or []
+        for var in (env_vars if isinstance(env_vars, list) else [env_vars]):
+            var = var.get("name") if isinstance(var, dict) else var
+            if isinstance(var, str) and var:
+                env[var] = "${" + var + "}"
+        block["env"] = env
+    elif table.get("url"):
+        block["type"] = "http"
+        block["url"] = str(table["url"])
+        headers = {}
+        if isinstance(table.get("http_headers"), dict):
+            headers.update({str(k): str(v) for k, v in table["http_headers"].items()})
+        if isinstance(table.get("env_http_headers"), dict):
+            headers.update({str(k): "${" + str(v) + "}" for k, v in table["env_http_headers"].items()})
+        if table.get("bearer_token_env_var"):
+            headers["Authorization"] = "Bearer ${" + str(table["bearer_token_env_var"]) + "}"
+        if headers:
+            block["headers"] = headers
+    else:
+        raise RegistryError(f"codex server {name!r} has neither a command nor a url")
+    for key in ("startup_timeout_sec", "tool_timeout_sec", "cwd", "enabled"):
+        if key in table:
+            block[key] = table[key]
+    extra = {key: copy.deepcopy(value) for key, value in table.items()
+             if key not in CODEX_MODELLED_KEYS}
+    if extra:
+        block["codex"] = extra
+    validate_block(name, block)
+    return block
+
+
+def _toml_key(key):
+    return key if BARE_KEY.match(key) else json.dumps(key, ensure_ascii=False)
+
+
+def _toml_value(value):
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        if not math.isfinite(value):
+            raise RegistryError("cannot write a non-finite number into config.toml")
+        return repr(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, list):
+        return "[" + ", ".join(_toml_value(item) for item in value) + "]"
+    if isinstance(value, dict):
+        return "{ " + ", ".join(f"{_toml_key(str(k))} = {_toml_value(v)}"
+                                for k, v in value.items()) + " }"
+    raise RegistryError(f"cannot write {type(value).__name__} into config.toml")
+
+
+def _toml_table(name, table):
+    lines = [f"[mcp_servers.{_toml_key(name)}]"]
+    for key, value in table.items():
+        lines.append(f"{_toml_key(str(key))} = {_toml_value(value)}")
+    return "\n".join(lines) + "\n"
+
+
+def _name_pattern(name):
+    escaped = re.escape(name)
+    return (r"(?:" + escaped + r"|\"" + escaped + r"\"|'" + escaped + r"')")
+
+
+def _strip_server_text(text, name):
+    """Drop every line that defines `mcp_servers.<name>` — its tables, its
+    sub-tables, a dotted key under a bare [mcp_servers] table, or a dotted root
+    key. Everything else is preserved byte for byte, including the comments and
+    blank lines that sit directly above the next table (they belong to it)."""
+    own_header = re.compile(r"^\s*\[\s*mcp_servers\s*\.\s*" + _name_pattern(name)
+                            + r"\s*(?:\.[^\]]*)?\]\s*(?:#.*)?$")
+    root_header = re.compile(r"^\s*\[\s*mcp_servers\s*\]\s*(?:#.*)?$")
+    any_header = re.compile(r"^\s*\[")
+    dotted_in_root = re.compile(r"^\s*" + _name_pattern(name) + r"\s*(?:\.|=)")
+    dotted_top = re.compile(r"^\s*mcp_servers\s*\.\s*" + _name_pattern(name) + r"\s*(?:\.|=)")
+    state = "top"
+    out, pending = [], []
+    for line in text.splitlines(keepends=True):
+        if any_header.match(line):
+            if own_header.match(line.rstrip("\r\n")):
+                state = "mine"
+                pending = []
+                continue
+            out.extend(pending)
+            pending = []
+            state = "root" if root_header.match(line.rstrip("\r\n")) else "other"
+            out.append(line)
+            continue
+        if state == "mine":
+            if not line.strip() or line.lstrip().startswith("#"):
+                pending.append(line)
+            else:
+                pending = []
+            continue
+        if state == "root" and dotted_in_root.match(line):
+            continue
+        if state == "top" and dotted_top.match(line):
+            continue
+        out.append(line)
+    out.extend(line for line in pending if line.strip())
+    return "".join(out)
+
+
+def _without(doc, names):
+    doc = copy.deepcopy(doc)
+    servers = doc.get("mcp_servers")
+    if isinstance(servers, dict):
+        for name in names:
+            servers.pop(name, None)
+        if not servers:
+            doc.pop("mcp_servers")
+    return doc
+
+
+def reconcile_codex_text(text, eff):
+    """Return (new_text, notes)."""
+    tomllib = _tomllib()
+    try:
+        current = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise RegistryError(f"config.toml does not parse: {exc}") from exc
+    existing = current.get("mcp_servers") if isinstance(current.get("mcp_servers"), dict) else {}
+    wanted, notes = {}, []
+    for name, block in eff.servers.items():
+        try:
+            table, block_notes = codex_block(name, block)
+        except RegistryError as exc:
+            notes.append(f"{exc} — skipped")
+            continue
+        notes.extend(block_notes)
+        if table is not None:
+            wanted[name] = table
+    retired = eff.retired | eff.retired_user
+    touched = [name for name, table in wanted.items() if existing.get(name) != table]
+    touched += [name for name in retired if name in existing]
+    if not touched:
+        return text, notes
+    result = text
+    for name in touched:
+        result = _strip_server_text(result, name)
+    additions = [_toml_table(name, wanted[name]) for name in touched if name in wanted]
+    if additions:
+        if result and not result.endswith("\n"):
+            result += "\n"
+        if result and not result.endswith("\n\n"):
+            result += "\n"
+        result += "\n".join(additions)
+    try:
+        parsed = tomllib.loads(result)
+    except tomllib.TOMLDecodeError as exc:
+        raise RegistryError(f"refusing to write config.toml: the edit would not parse ({exc})") from exc
+    if _without(parsed, touched) != _without(current, touched):
+        raise RegistryError("refusing to write config.toml: an unrelated setting would change "
+                            "(unsupported layout for mcp_servers)")
+    written = parsed.get("mcp_servers") if isinstance(parsed.get("mcp_servers"), dict) else {}
+    for name in touched:
+        if name in wanted and written.get(name) != wanted[name]:
+            raise RegistryError(f"refusing to write config.toml: {name} did not round-trip")
+        if name not in wanted and name in written:
+            raise RegistryError(f"refusing to write config.toml: {name} could not be removed")
+    return result, notes
+
+
+def apply_codex(account_dir, eff):
+    path = os.path.join(account_dir, CONFIG_FILE["codex"])
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except FileNotFoundError:
+        text = ""
+    except (OSError, UnicodeDecodeError) as exc:
+        raise RegistryError(f"{path}: {exc}") from exc
+    result, notes = reconcile_codex_text(text, eff)
+    label = os.path.basename(account_dir.rstrip("/"))
+    for note in notes:
+        _warn(f"{label}: {note}")
+    if result == text and os.path.exists(path):
+        return "unchanged"
+    _atomic_write(path, result)
+    return "updated"
+
+
+def snapshot_codex(account_dir):
+    tomllib = _tomllib()
+    path = os.path.join(account_dir, CONFIG_FILE["codex"])
+    try:
+        with open(path, encoding="utf-8") as handle:
+            doc = tomllib.loads(handle.read())
+    except FileNotFoundError:
+        doc = {}
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
+        raise RegistryError(f"{path}: {exc}") from exc
+    servers = doc.get("mcp_servers") if isinstance(doc.get("mcp_servers"), dict) else {}
+    return {"provider": "codex",
+            "user": {name: table for name, table in servers.items() if isinstance(table, dict)}}
+
+
+# ---------------------------------------------------------------- reconcile
+
+def apply_account(root, provider, account_dir):
+    eff = effective(load_registry(root), load_overlay(root))
+    if provider == "claude":
+        state = apply_claude(account_dir, eff)
+    else:
+        state = apply_codex(account_dir, eff)
+    write_stamp(root, provider, account_dir)
+    return state
+
+
+def apply_many(root, provider, account_dirs, quiet=False, fail_open=False):
+    """Reconcile each dir; returns the number of accounts that could not be."""
+    failures = 0
+    for account_dir in account_dirs:
+        label = os.path.basename(account_dir.rstrip("/"))
+        if not os.path.isdir(account_dir):
+            if not quiet:
+                print(f"{label}: skipped (no such directory)")
+            continue
+        try:
+            state = apply_account(root, provider, account_dir)
+        except Exception as exc:  # noqa: BLE001 — one account must never stop the rest
+            failures += 1
+            _warn(f"{label}: {type(exc).__name__ if not isinstance(exc, RegistryError) else ''}"
+                  f"{': ' if not isinstance(exc, RegistryError) else ''}{exc}")
+            continue
+        if not quiet:
+            print(f"{label}: {state}")
+    return failures
+
+
+def _registry_present(root):
+    return any(os.path.exists(os.path.join(root, name)) for name in (REGISTRY_FILE, OVERLAY_FILE))
+
+
+# ------------------------------------------------------------------- learn
+
+def snapshot(provider, account_dir):
+    return snapshot_claude(account_dir) if provider == "claude" else snapshot_codex(account_dir)
+
+
+def _learn_into(section, before, after):
+    """Mirror the difference between two snapshots into a section (registry or
+    overlay owner). Returns human-readable change descriptions (empty = nothing)."""
+    changes = []
+    provider = after.get("provider")
+    before_user, after_user = before.get("user") or {}, after.get("user") or {}
+    for name, block in after_user.items():
+        if before_user.get(name) == block:
+            continue
+        try:
+            learned = block if provider == "claude" else codex_to_claude(name, block)
+            validate_block(name, learned)
+        except RegistryError as exc:
+            _warn(f"not mirrored: {exc}")
+            continue
+        section["mcpServers"][name] = learned
+        section["retired"] = [n for n in section["retired"] if n != name]
+        section["retiredUser"] = [n for n in section["retiredUser"] if n != name]
+        changes.append(f'"{name}"')
+    for name in before_user:
+        if name not in after_user:
+            section["mcpServers"].pop(name, None)
+            # The client removed the USER-scope entry and nothing else: mirror exactly
+            # that. Project entries of the same name stay, in every account.
+            if name not in section["retiredUser"] and name not in section["retired"]:
+                section["retiredUser"].append(name)
+            changes.append(f'"{name}" (removed)')
+    if provider != "claude":
+        return changes
+    before_projects, after_projects = before.get("projects") or {}, after.get("projects") or {}
+    for path in sorted(set(before_projects) | set(after_projects)):
+        old, new = before_projects.get(path) or {}, after_projects.get(path) or {}
+        old_mcp, new_mcp = old.get("mcpServers") or {}, new.get("mcpServers") or {}
+        for name, block in new_mcp.items():
+            if old_mcp.get(name) != block:
+                try:
+                    validate_block(name, block)
+                except RegistryError as exc:
+                    _warn(f"not mirrored: {exc}")
+                    continue
+                entry = section["projects"].setdefault(path, {"mcpServers": {}, "retired": []})
+                entry.setdefault("mcpServers", {})[name] = block
+                entry["retired"] = [n for n in entry.get("retired", []) if n != name]
+                changes.append(f'"{name}" (project {path})')
+        for name in old_mcp:
+            if name not in new_mcp:
+                entry = section["projects"].setdefault(path, {"mcpServers": {}, "retired": []})
+                entry.setdefault("mcpServers", {}).pop(name, None)
+                entry.setdefault("retired", [])
+                if name not in entry["retired"]:
+                    entry["retired"].append(name)
+                changes.append(f'"{name}" (removed from project {path})')
+        old_enabled = set(old.get("enabledMcpjsonServers") or [])
+        new_enabled = set(new.get("enabledMcpjsonServers") or [])
+        if new_enabled - old_enabled:
+            entry = section["projects"].setdefault(path, {"mcpServers": {}, "retired": []})
+            current = entry.get("enabledMcpjsonServers")
+            current = list(current) if isinstance(current, list) else []
+            for name in sorted(new_enabled - old_enabled):
+                if name not in current:
+                    current.append(name)
+            entry["enabledMcpjsonServers"] = current
+            changes.append(f"approved .mcp.json servers for project {path}")
+    return changes
+
+
+# --------------------------------------------------------------------- CLI
+
+def _parse_env(items):
+    env = {}
+    for item in items or []:
+        if "=" not in item:
+            raise RegistryError(f"-e expects KEY=VALUE, got {item!r}")
+        key, value = item.split("=", 1)
+        env[key] = value
+    return env
+
+
+def _parse_headers(items):
+    headers = {}
+    for item in items or []:
+        if ":" not in item:
+            raise RegistryError(f"-H expects 'Header: value', got {item!r}")
+        key, value = item.split(":", 1)
+        headers[key.strip()] = value.strip()
+    return headers
+
+
+def _split_command(argv):
+    if "--" in argv:
+        index = argv.index("--")
+        return argv[:index], argv[index + 1:]
+    return argv, []
+
+
+def _normalize_project(path):
+    if not path:
+        return path
+    return os.path.realpath(os.path.expanduser(path))
+
+
+class _Target:
+    """Where a mutation lands: the synced registry, or — on a replica, whose registry
+    the source machine overwrites on every push — this machine's overlay."""
+
+    def __init__(self, root):
+        self.root = root
+        self.replica = is_replica(root)
+        self.overlay = load_overlay(root) if self.replica else None
+        if self.replica:
+            self.section = self.overlay["owners"].setdefault("local", _normalize_section({}))
+        else:
+            self.section = load_registry(root)
+
+    def save(self):
+        if self.replica:
+            save_overlay(self.root, self.overlay)
+        else:
+            save_registry(self.root, self.section)
+
+    @property
+    def where(self):
+        return "this machine's overlay (replica pool)" if self.replica else "the registry"
+
+
+def _upsert(section, name, block, scope, project):
+    if scope == "project":
+        if not project:
+            raise RegistryError("--scope project needs --project PATH")
+        entry = section["projects"].setdefault(project, {"mcpServers": {}, "retired": []})
+        entry.setdefault("mcpServers", {})[name] = block
+        entry["retired"] = [n for n in entry.get("retired", []) if n != name]
+    else:
+        section["mcpServers"][name] = block
+        section["retired"] = [n for n in section["retired"] if n != name]
+        section["retiredUser"] = [n for n in section["retiredUser"] if n != name]
+
+
+def _retire(section, name, scope, project, user_only=False):
+    if scope == "project":
+        if not project:
+            raise RegistryError("--scope project needs --project PATH")
+        entry = section["projects"].setdefault(project, {"mcpServers": {}, "retired": []})
+        entry.setdefault("mcpServers", {}).pop(name, None)
+        entry.setdefault("retired", [])
+        if name not in entry["retired"]:
+            entry["retired"].append(name)
+        return
+    section["mcpServers"].pop(name, None)
+    key, other = ("retiredUser", "retired") if user_only else ("retired", "retiredUser")
+    if name not in section[key]:
+        section[key].append(name)
+    section[other] = [n for n in section[other] if n != name]
+
+
+def _describe(block):
+    if not isinstance(block, dict):
+        return "invalid block"
+    kind = _kind_of(block)
+    if kind == "stdio":
+        args = block.get("args") or []
+        args = args if isinstance(args, list) else [args]
+        return f"{kind:5} " + " ".join(shlex.quote(str(x)) for x in [block.get("command", "")] + args)
+    return f"{kind:5} {block.get('url', '')}"
+
+
+def cmd_list(args):
+    registry = load_registry(args.root)
+    overlay = load_overlay(args.root)
+    eff = effective(registry, overlay)
+    if args.json:
+        print(json.dumps({"mcpServers": eff.servers, "retired": sorted(eff.retired),
+                          "retiredUser": sorted(eff.retired_user), "projects": eff.projects,
+                          "overlayOwners": sorted(overlay.get("owners", {})),
+                          "replica": is_replica(args.root)}, indent=2))
+        return 0
+    if not eff.servers and not eff.retired and not eff.retired_user and not eff.projects:
+        print(f"no MCP servers registered for the {args.provider} pool")
+        return 0
+    if eff.servers:
+        print("servers (every account):")
+        for name in sorted(eff.servers):
+            origin = "registry" if name in registry["mcpServers"] else "overlay"
+            print(f"  {name:24} {_describe(eff.servers[name])}  [{origin}]")
+    if eff.retired:
+        print("retired (removed from every account, every scope): " + ", ".join(sorted(eff.retired)))
+    if eff.retired_user:
+        print("retired at user scope only: " + ", ".join(sorted(eff.retired_user)))
+    for path, entry in sorted(eff.projects.items()):
+        print(f"project {path}:")
+        for name in sorted(entry.get("mcpServers") or {}):
+            print(f"  {name:24} {_describe(entry['mcpServers'][name])}")
+        if entry.get("retired"):
+            print("  retired: " + ", ".join(sorted(entry["retired"])))
+        if entry.get("enabledMcpjsonServers"):
+            print("  approved .mcp.json servers: " + ", ".join(entry["enabledMcpjsonServers"]))
+    if is_replica(args.root):
+        print("(replica pool: changes made here stay in this machine's overlay; make fleet-wide "
+              "changes on the source machine)")
+    return 0
+
+
+def _apply_all(args, quiet):
+    dirs = manifest_account_dirs(args.root)
+    if not dirs and not quiet:
+        print("no accounts in the manifest yet — the registry applies as accounts are added")
+    failures = apply_many(args.root, args.provider, dirs, quiet=quiet)
+    if failures:
+        _warn(f"{failures} account(s) not reconciled — fix them and run: "
+              f"{args.provider}-accounts mcp apply")
+        return EXIT_PARTIAL
+    return 0
+
+
+def cmd_add(args, command, leftovers):
+    _validate_name(args.name)
+    url = args.url
+    if leftovers:
+        if url or len(leftovers) > 1 or leftovers[0].startswith("-"):
+            raise RegistryError(f"unexpected argument(s): {' '.join(leftovers)}")
+        url = leftovers[0]
+    transport = args.transport
+    if transport is None:
+        transport = "http" if (url and not command) else "stdio"
+    if transport == "stdio":
+        if not command:
+            raise RegistryError("a stdio server needs `-- COMMAND [ARGS...]`")
+        block = {"type": "stdio", "command": command[0], "args": command[1:],
+                 "env": _parse_env(args.env)}
+    else:
+        if not url:
+            raise RegistryError(f"a {transport} server needs its URL (--url URL)")
+        block = {"type": transport, "url": url}
+        headers = _parse_headers(args.header)
+        if headers:
+            block["headers"] = headers
+    validate_block(args.name, block)
+    return _store(args, block)
+
+
+def cmd_add_json(args, leftovers):
+    if leftovers:
+        raise RegistryError(f"unexpected argument(s): {' '.join(leftovers)}")
+    _validate_name(args.name)
+    try:
+        block = json.loads(args.block)
+    except ValueError as exc:
+        raise RegistryError(f"not JSON: {exc}") from exc
+    validate_block(args.name, block)
+    return _store(args, block)
+
+
+def _store(args, block):
+    project = _normalize_project(args.project)
+    with _Lock(args.root):
+        target = _Target(args.root)
+        _upsert(target.section, args.name, block, args.scope, project)
+        target.save()
+    where = f"project {project}" if args.scope == "project" else "user scope"
+    _log(args.root, f"add {args.name} ({where}) {_describe(block)}")
+    print(f"registered {args.name} ({where}) in {target.where} for every {args.provider} account")
+    return _apply_all(args, quiet=False)
+
+
+def cmd_remove(args, leftovers):
+    if leftovers:
+        raise RegistryError(f"unexpected argument(s): {' '.join(leftovers)}")
+    _validate_name(args.name, strict=False)
+    project = _normalize_project(args.project)
+    with _Lock(args.root):
+        target = _Target(args.root)
+        _retire(target.section, args.name, args.scope, project, user_only=args.user_only)
+        target.save()
+    if args.scope == "project":
+        where = f"project {project}"
+    else:
+        where = "user scope only" if args.user_only else "every scope"
+    _log(args.root, f"remove {args.name} ({where})")
+    print(f"retired {args.name} ({where}) in {target.where}: removed from every "
+          f"{args.provider} account")
+    return _apply_all(args, quiet=False)
+
+
+def cmd_apply(args, leftovers):
+    if leftovers:
+        raise RegistryError(f"unexpected argument(s): {' '.join(leftovers)}")
+    if args.all or not args.account_dir:
+        rc = _apply_all(args, quiet=args.quiet)
+        return 0 if args.fail_open else rc
+    failures = apply_many(args.root, args.provider, args.account_dir, quiet=args.quiet)
+    return 0 if args.fail_open or not failures else 1
+
+
+def cmd_snapshot(args):
+    print(json.dumps(snapshot(args.provider, args.account_dir)))
+    return 0
+
+
+def cmd_learn(args):
+    try:
+        with open(args.before, encoding="utf-8") as handle:
+            before = json.load(handle)
+    except (OSError, ValueError) as exc:
+        raise RegistryError(f"snapshot {args.before}: {exc}") from exc
+    after = snapshot(args.provider, args.account_dir)
+    with _Lock(args.root):
+        target = _Target(args.root)
+        changes = _learn_into(target.section, before, after)
+        if changes:
+            target.save()
+    if not changes:
+        return 0
+    _log(args.root, "learn " + ", ".join(changes))
+    dirs = manifest_account_dirs(args.root)
+    failures = apply_many(args.root, args.provider, dirs, quiet=True)
+    print(f"mcp-registry: mirrored {', '.join(changes)} to {len(dirs)} {args.provider} "
+          f"account(s) via {target.where}", file=sys.stderr)
+    if target.replica:
+        print("mcp-registry: this pool is a replica — the change stays on this machine; "
+              "make fleet-wide changes on the source machine", file=sys.stderr)
+    return EXIT_PARTIAL if failures else 0
+
+
+def cmd_import_local(args):
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except ValueError as exc:
+        raise RegistryError(f"stdin is not JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise RegistryError("stdin must hold a JSON object")
+    servers = payload.get("mcpServers") or {}
+    retired = payload.get("retired") or []
+    if not isinstance(servers, dict) or not isinstance(retired, list):
+        raise RegistryError("expected {\"mcpServers\": {...}, \"retired\": [...]}")
+    owner = _validate_name(args.owner)
+    for name in list(servers):
+        _validate_name(name)
+        validate_block(name, servers[name])
+    retired = [_validate_name(str(name), strict=False) for name in retired]
+    with _Lock(args.root):
+        overlay = load_overlay(args.root)
+        previous = overlay["owners"].get(owner) or _normalize_section({})
+        # A server this owner published before and no longer names is retired for
+        # it: an owner that stops shipping a server means it, and every account
+        # would otherwise keep the stale copy for ever.
+        dropped = [name for name in previous["mcpServers"] if name not in servers]
+        section = _normalize_section({"mcpServers": servers,
+                                      "retired": sorted(set(retired) | set(dropped))})
+        if previous == section and owner in overlay["owners"]:
+            changed = False
+        else:
+            overlay["owners"][owner] = section
+            save_overlay(args.root, overlay)
+            changed = True
+    if changed:
+        _log(args.root, f"import-local owner={owner} servers={','.join(sorted(servers)) or '-'} "
+                        f"retired={','.join(sorted(section['retired'])) or '-'}")
+    return _apply_all(args, quiet=args.quiet)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog="mcp_registry.py", description=__doc__.split("\n\n")[0])
+    parser.add_argument("--root", required=True, help="pool root (holds accounts.json)")
+    parser.add_argument("--provider", required=True, choices=PROVIDERS)
+    modes = parser.add_subparsers(dest="mode")
+
+    p = modes.add_parser("list")
+    p.add_argument("--json", action="store_true")
+
+    for mode in ("add", "add-json"):
+        p = modes.add_parser(mode)
+        p.add_argument("name")
+        if mode == "add-json":
+            p.add_argument("block", help="Claude-style JSON block")
+        else:
+            p.add_argument("--url", help="URL for --transport http/sse (a bare URL argument works too)")
+            p.add_argument("--transport", choices=("stdio", "http", "sse"))
+            p.add_argument("-e", "--env", action="append", default=[])
+            p.add_argument("-H", "--header", action="append", default=[])
+        p.add_argument("--scope", choices=("user", "project"), default="user")
+        p.add_argument("--project")
+
+    p = modes.add_parser("remove")
+    p.add_argument("name")
+    p.add_argument("--scope", choices=("user", "project"), default="user")
+    p.add_argument("--project")
+    p.add_argument("--user-only", action="store_true",
+                   help="retire the user-scope entry only; project entries keep the name")
+
+    p = modes.add_parser("apply")
+    p.add_argument("--account-dir", action="append", default=[])
+    p.add_argument("--all", action="store_true")
+    p.add_argument("--fail-open", action="store_true")
+    p.add_argument("--quiet", action="store_true")
+
+    p = modes.add_parser("snapshot")
+    p.add_argument("--account-dir", required=True)
+
+    p = modes.add_parser("learn")
+    p.add_argument("--account-dir", required=True)
+    p.add_argument("--before", required=True)
+    p.add_argument("--project", help="accepted for the shim's sake; every changed project is mirrored")
+
+    p = modes.add_parser("import-local")
+    p.add_argument("--owner", required=True)
+    p.add_argument("--quiet", action="store_true")
+    return parser
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    head, command = _split_command(argv)
+    parser = build_parser()
+    # parse_known_args, not parse_args: an optional positional after options (the URL
+    # in `add NAME --transport http URL`) is "unrecognized" to argparse before 3.12.
+    args, leftovers = parser.parse_known_args(head)
+    if not args.mode:
+        parser.error("a mode is required (list, add, add-json, remove, apply, snapshot, "
+                     "learn, import-local)")
+    if not os.path.isdir(args.root):
+        raise RegistryError(f"pool root {args.root} does not exist")
+    if args.provider == "codex" and sys.version_info < (3, 11):
+        from codex_python import require_python311
+        require_python311(os.path.abspath(__file__))
+    if args.mode == "apply" and not _registry_present(args.root):
+        return 0   # nothing registered: every account is already "reconciled"
+    if args.mode == "list":
+        return cmd_list(args)
+    if args.mode == "add":
+        return cmd_add(args, command, leftovers)
+    if args.mode == "add-json":
+        return cmd_add_json(args, leftovers)
+    if args.mode == "remove":
+        return cmd_remove(args, leftovers)
+    if args.mode == "apply":
+        return cmd_apply(args, leftovers)
+    if leftovers:
+        raise RegistryError(f"unexpected argument(s): {' '.join(leftovers)}")
+    if args.mode == "snapshot":
+        return cmd_snapshot(args)
+    if args.mode == "learn":
+        return cmd_learn(args)
+    if args.mode == "import-local":
+        return cmd_import_local(args)
+    parser.error(f"unknown mode {args.mode}")
+    return 2
+
+
+if __name__ == "__main__":
+    fail_open = "--fail-open" in sys.argv
+    try:
+        sys.exit(main())
+    except RegistryError as error:
+        _warn(str(error))
+        sys.exit(0 if fail_open else 1)
+    except SystemExit as error:
+        # argparse usage errors and codex_python's "no python 3.11" both land here.
+        if fail_open and error.code not in (0, None):
+            if isinstance(error.code, str):
+                _warn(error.code)
+            sys.exit(0)
+        raise
+    except Exception as error:  # noqa: BLE001 — a traceback is never the shim's problem
+        _warn(f"{type(error).__name__}: {error}")
+        sys.exit(0 if fail_open else 1)