scripts(fix[mcp_swap]): preserve existing env on use-local replacement

cmd_use_local previously constructed the replacement spec via
build_local_spec (which leaves env={}) and wrote it directly. Any
env entries the user had set on the prior pinned-PyPI block —
LIBTMUX_SAFETY, LIBTMUX_SOCKET, custom dev knobs — were silently
dropped on swap. The timestamped backup at .bak.mcp-swap-<ts> still
captured the original config so revert restored everything, but a
day-to-day swap shouldn't require manual env restoration.

Merge current.env into the new spec via dataclasses.replace before
set_server. The merge is symmetric with _spec_from_entry, which
already round-trips env on the read side. Only fires when current is
not None, so the Codex "added" path keeps writing empty env.

Two regression tests: one seeds env on a Cursor entry and asserts
preservation through swap; the paired test pins the no-prior-entry
Codex path to lock the merge logic against accidental env synthesis.

Author: tony

CHANGES

@@ -40,6 +40,19 @@ _Notes on upcoming releases will be added here_
 
 ### Scripts
 
+- ``scripts/mcp_swap.py``: ``use-local`` now preserves an existing
+  entry's ``env`` dict on replacement. Previously a swap silently
+  dropped client-side environment settings (``LIBTMUX_SAFETY``,
+  ``LIBTMUX_SOCKET``, custom dev knobs) because ``build_local_spec``
+  returned a spec with empty env and ``set_server`` wrote it unchanged.
+  The timestamped backup at ``.bak.mcp-swap-<ts>`` still captures the
+  full original config for full recovery via ``revert``, but day-to-day
+  swaps no longer require manual env restoration. The merge mirrors
+  ``_spec_from_entry`` (which round-trips env on the read side).
+  Regression test:
+  ``tests/test_mcp_swap.py:test_use_local_preserves_existing_env_when_replacing``
+  plus a paired ``test_use_local_with_no_prior_entry_writes_empty_env``
+  to lock the Codex "added" path against accidental env synthesis.
 - ``scripts/mcp_swap.py``: ``_claude_project_node`` validates that
   Claude's undocumented ``projects.<abs>.mcpServers`` layout is still
   mapping-shaped before mutating it. If a future Claude release

scripts/mcp_swap.py

@@ -556,7 +556,13 @@ def cmd_use_local(args: argparse.Namespace) -> int:
         ):
             print(f"[{cli}] already local (this repo) — no change")
             continue
-        action = set_server(cli, config, server, spec, repo)
+        # Preserve the existing entry's env on replacement. ``build_local_spec``
+        # writes an empty env, so without this merge a swap would silently drop
+        # client-side settings (LIBTMUX_SAFETY, LIBTMUX_SOCKET, custom dev
+        # knobs). Symmetric with ``_spec_from_entry`` which round-trips env on
+        # the read side.
+        cli_spec = dataclasses.replace(spec, env={**current.env}) if current else spec
+        action = set_server(cli, config, server, cli_spec, repo)
         new_bytes = dump_config_bytes(info, config)
 
         if args.dry_run:

tests/test_mcp_swap.py

@@ -158,6 +158,76 @@ def test_json_swap_and_revert_round_trip(
     assert info.config_path.read_bytes() == original
 
 
+def test_use_local_preserves_existing_env_when_replacing(
+    fake_home: pathlib.Path, fake_repo: pathlib.Path
+) -> None:
+    """Existing ``env`` on a replaced entry survives ``use-local``.
+
+    Regression: ``cmd_use_local`` previously constructed the replacement
+    spec via ``build_local_spec`` (env={}) and wrote it directly,
+    silently dropping client-side settings like ``LIBTMUX_SAFETY`` or
+    ``LIBTMUX_SOCKET`` that the user had set on the prior pinned-PyPI
+    entry. The fix merges ``current.env`` into the new spec; this test
+    locks the behaviour by seeding env on a Cursor entry, running
+    ``use-local``, and asserting both the new local-uv command shape and
+    the original env survived.
+    """
+    info = mcp_swap.CLIS["cursor"]
+    _write_json(
+        info.config_path,
+        {
+            "mcpServers": {
+                "libtmux": {
+                    "command": "uvx",
+                    "args": ["libtmux-mcp==0.1.0a2"],
+                    "env": {"LIBTMUX_SAFETY": "readonly", "FOO": "bar"},
+                }
+            }
+        },
+    )
+
+    args = mcp_swap.build_parser().parse_args(
+        ["use-local", "--repo", str(fake_repo), "--cli", "cursor"]
+    )
+    assert mcp_swap.cmd_use_local(args) == 0
+
+    entry = json.loads(info.config_path.read_text())["mcpServers"]["libtmux"]
+    assert entry["command"] == "uv"
+    assert entry["args"] == [
+        "--directory",
+        str(fake_repo.resolve()),
+        "run",
+        "libtmux-mcp",
+    ]
+    assert entry["env"] == {"LIBTMUX_SAFETY": "readonly", "FOO": "bar"}
+
+
+def test_use_local_with_no_prior_entry_writes_empty_env(
+    fake_home: pathlib.Path, fake_repo: pathlib.Path
+) -> None:
+    """When no prior entry exists, the new spec lands with empty env.
+
+    The env-merge branch only fires for replacements; the "added" path
+    (e.g. Codex with no prior libtmux block) should match
+    ``build_local_spec``'s default empty env. This pins the Codex add
+    case so the merge logic doesn't accidentally synthesise env from
+    nothing.
+    """
+    info = mcp_swap.CLIS["codex"]
+    info.config_path.parent.mkdir(parents=True, exist_ok=True)
+    info.config_path.write_text("# empty config\n")
+
+    args = mcp_swap.build_parser().parse_args(
+        ["use-local", "--repo", str(fake_repo), "--cli", "codex"]
+    )
+    assert mcp_swap.cmd_use_local(args) == 0
+
+    config = tomlkit.parse(info.config_path.read_text())
+    table = config["mcp_servers"]["libtmux"]  # type: ignore[index]
+    assert isinstance(table, tomlkit.items.Table)
+    assert "env" not in table
+
+
 def test_json_swap_preserves_unrelated_servers(
     fake_home: pathlib.Path, fake_repo: pathlib.Path
 ) -> None: