fix(dsh): ensure config home exists before wrap dsh registration

DshRegistrar.detect() requires ~/.dsh to exist, so on a fresh install
headroom wrap dsh registered nothing and dsh created its home without
Serena. Add DshRegistrar.ensure_home() and call it on the explicit wrap
path before registration; detect() stays conservative for global
headroom mcp install.

Wrap tests redirect DSH_HOME / HEADROOM_WORKSPACE_DIR / HOME to tmp so
they cannot mutate a developer's real ~/.dsh, and a new test proves the
managed entry exists before launch when no DSH home is present.

Author: Zenjibad

headroom/cli/wrap.py

@@ -7519,7 +7519,9 @@ def dsh(
 
     from headroom.mcp_registry import DshRegistrar
 
-    _setup_coding_compressor(DshRegistrar(), serena_context="agent", verbose=verbose)
+    registrar = DshRegistrar()
+    registrar.ensure_home()
+    _setup_coding_compressor(registrar, serena_context="agent", verbose=verbose)
 
     _launch_tool(
         binary=argv[0],

headroom/mcp_registry/dsh.py

@@ -175,6 +175,16 @@ def _config_file(self) -> Path:
     def detect(self) -> bool:
         return _dsh_home().exists()
 
+    def ensure_home(self) -> None:
+        """Create the dsh config home if missing (explicit wrap path only).
+
+        ``headroom wrap dsh`` targets a harness that is about to launch, so it
+        must register before dsh creates its own home on first boot. Global
+        ``headroom mcp install`` detection stays conservative: ``detect()``
+        still requires an existing home.
+        """
+        _dsh_home().mkdir(parents=True, exist_ok=True)
+
     def get_server(self, server_name: str) -> ServerSpec | None:
         managed = _read_managed_block(self._config_file)
         if managed.entries is None:

tests/test_cli/test_wrap_dsh.py

@@ -20,9 +20,28 @@ def fake_launch_tool(**kwargs: object) -> None:
     return fake_launch_tool
 
 
+def _hermetic_home(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    """Redirect every home-adjacent path the wrap flow can write to.
+
+    The wrap flow registers Serena/headroom MCP entries into the dsh home and
+    records installs in the Headroom workspace ledger. Without redirects these
+    tests would mutate the developer's real `~/.dsh` / `~/.headroom` when
+    the harness is installed on the machine running the suite.
+    """
+    monkeypatch.setenv("DSH_HOME", str(tmp_path / "dsh"))
+    monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / "headroom"))
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    # The repo root carries a `.serena/project.yml`, so a successful Serena
+    # registration would synchronously run `serena project index` (a real
+    # subprocess, up to _SERENA_INDEX_TIMEOUT). Registration is what these
+    # tests assert; the pre-index is orthogonal and must not run here.
+    monkeypatch.setattr("headroom.cli.wrap._index_serena_project", lambda **_kwargs: None)
+
+
 def test_wrap_dsh_launches_web_with_proxy_env(
-    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
 ) -> None:
+    _hermetic_home(monkeypatch, tmp_path)
     captured: dict[str, object] = {}
     monkeypatch.setattr("headroom.cli.wrap._launch_tool", _capture(captured))
     monkeypatch.setattr(
@@ -40,7 +59,10 @@ def test_wrap_dsh_launches_web_with_proxy_env(
     assert captured["agent_type"] == "dsh"
 
 
-def test_wrap_dsh_headless_profile(runner: CliRunner, monkeypatch: pytest.MonkeyPatch) -> None:
+def test_wrap_dsh_headless_profile(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _hermetic_home(monkeypatch, tmp_path)
     captured: dict[str, object] = {}
     monkeypatch.setattr("headroom.cli.wrap._launch_tool", _capture(captured))
     monkeypatch.setattr(
@@ -54,8 +76,9 @@ def test_wrap_dsh_headless_profile(runner: CliRunner, monkeypatch: pytest.Monkey
 
 
 def test_wrap_dsh_forwards_deepseek_api_url(
-    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
 ) -> None:
+    _hermetic_home(monkeypatch, tmp_path)
     captured: dict[str, object] = {}
     monkeypatch.setattr("headroom.cli.wrap._launch_tool", _capture(captured))
     monkeypatch.setattr(
@@ -69,8 +92,9 @@ def test_wrap_dsh_forwards_deepseek_api_url(
 
 
 def test_wrap_dsh_captures_ambient_deepseek_base_url(
-    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
 ) -> None:
+    _hermetic_home(monkeypatch, tmp_path)
     captured: dict[str, object] = {}
     monkeypatch.setattr("headroom.cli.wrap._launch_tool", _capture(captured))
     monkeypatch.setattr("headroom.providers.dsh.runtime.shutil.which", lambda _name: "/usr/bin/dsh")
@@ -80,15 +104,21 @@ def test_wrap_dsh_captures_ambient_deepseek_base_url(
     assert captured["deepseek_api_url"] == "https://gateway.internal"
 
 
-def test_wrap_dsh_missing_binary_fails(runner: CliRunner, monkeypatch: pytest.MonkeyPatch) -> None:
+def test_wrap_dsh_missing_binary_fails(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _hermetic_home(monkeypatch, tmp_path)
     monkeypatch.setattr("headroom.providers.dsh.runtime.shutil.which", lambda _name: None)
 
     result = runner.invoke(main, ["wrap", "dsh"])
     assert result.exit_code == 1
     assert "not found in PATH" in result.output
 
 
-def test_unwrap_dsh_stops_proxy(runner: CliRunner, monkeypatch: pytest.MonkeyPatch) -> None:
+def test_unwrap_dsh_stops_proxy(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    _hermetic_home(monkeypatch, tmp_path)
     monkeypatch.setattr(
         "headroom.cli.wrap._stop_local_proxy_for_unwrap",
         lambda _port: "stopped",
@@ -100,3 +130,39 @@ def test_unwrap_dsh_stops_proxy(runner: CliRunner, monkeypatch: pytest.MonkeyPat
 
     result = runner.invoke(main, ["unwrap", "dsh"])
     assert result.exit_code == 0, result.output
+
+
+def test_wrap_dsh_establishes_managed_entry_before_launch_without_home(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    """Fresh install: no DSH home exists — the managed entry must land before
+    dsh launches (review #4985851059: detect() alone would skip registration).
+    """
+    _hermetic_home(monkeypatch, tmp_path)
+    dsh_home = tmp_path / "dsh"
+    assert not dsh_home.exists()
+
+    captured: dict[str, object] = {}
+    launch_saw_entry: list[bool] = []
+
+    def fake_launch_tool(**kwargs: object) -> None:
+        # Prove the managed entry already exists at launch time.
+        launch_saw_entry.append((dsh_home / "cordis.patch.yml").exists())
+        captured.update(kwargs)
+
+    monkeypatch.setattr("headroom.cli.wrap._launch_tool", fake_launch_tool)
+    monkeypatch.setattr(
+        "headroom.providers.dsh.runtime.shutil.which",
+        lambda _name: "/usr/bin/dsh",
+    )
+
+    result = runner.invoke(main, ["wrap", "dsh", "--port", "9000"])
+    assert result.exit_code == 0, result.output
+
+    patch = dsh_home / "cordis.patch.yml"
+    assert patch.exists(), "managed entry must exist before dsh launches"
+    text = patch.read_text(encoding="utf-8")
+    assert "@deepseek-ai/dsh-mcp-client" in text
+    assert "serverName: serena" in text
+    assert captured["agent_type"] == "dsh"
+    assert launch_saw_entry == [True]

tests/test_mcp_registry_dsh.py

@@ -34,6 +34,31 @@ def test_not_detected_without_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Pa
     assert DshRegistrar().detect() is False
 
 
+def test_ensure_home_creates_missing_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    home = tmp_path / "dsh"
+    monkeypatch.setenv("DSH_HOME", str(home))
+    reg = DshRegistrar()
+    assert reg.detect() is False
+    reg.ensure_home()
+    assert reg.detect() is True
+    assert home.is_dir()
+
+
+def test_register_after_ensure_home_without_home(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """Fresh install: no DSH home yet — the explicit wrap path must be able to
+    register before dsh creates its home on first boot."""
+    home = tmp_path / "dsh"
+    monkeypatch.setenv("DSH_HOME", str(home))
+    reg = DshRegistrar()
+    reg.ensure_home()
+    result = reg.register_server(_spec())
+    assert result.status is RegisterStatus.REGISTERED
+    text = (home / "cordis.patch.yml").read_text(encoding="utf-8")
+    assert "@deepseek-ai/dsh-mcp-client" in text
+
+
 def test_register_writes_patch(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
     home = tmp_path / "dsh"
     home.mkdir()