feat(cli): use install_shim for engine bootstrap on first run

Previously cli.main called bootstrap.ensure_engine() which blocked MCP
initialize for 30-60s while downloading the ~45 MB engine bundle, leaving
BioRouter's UI hung with no progress feedback.

Now cli.main checks bootstrap.cached_launcher() (read-only). If cached, we
proxy immediately. If not, we serve install_shim which exposes a single
codegraphagent_check_engine tool. The agent invokes this tool deliberately;
the wait surfaces as a clear 'this will take a moment' message instead of
a silent stall. On success the shim returns the launcher and we transition
to proxy mode.

Author: Broccolito

src/codegraphagent/cli.py

@@ -1,29 +1,43 @@
 """CLI entry point for codegraphagent.
 
-Orchestrates the three pieces of the shim:
+Orchestrates the three (or four) pieces of the shim:
   1. paths — resolve the project root and ensure the .biorouter/codegraph
      state dir + .codegraph symlink exist.
-  2. bootstrap — ensure the vendored engine bundle is downloaded, verified,
-     and extracted.
-  3. proxy — spawn the engine and pump MCP traffic.
+  2. bootstrap.cached_launcher — read-only check: is the engine bundle
+     already installed?
+  3. install_shim (only if not cached) — serves a minimal MCP server with
+     a single tool (codegraphagent_check_engine) that downloads + extracts
+     the engine on demand. Returns the launcher path when install succeeds.
+  4. proxy — spawn the engine and pump MCP traffic.
 
-If either of the first two fails, hand control to the degraded-mode error
-shim so the agent gets a structured error frame rather than an opaque crash.
+If the layout step fails (LayoutConflictError), we serve the legacy error_shim
+to surface that failure to the agent as a tool error. BootstrapError no longer
+happens in this function — it's caught inside install_shim and returned as a
+tool result so the user can see it and retry.
 """
 
 from __future__ import annotations
 
-from codegraphagent import bootstrap, error_shim, paths, proxy
+from codegraphagent import bootstrap, error_shim, install_shim, paths, proxy
 from codegraphagent.errors import CodeGraphAgentError
 
 
 def main() -> int:
     try:
         root = paths.resolve_project_root()
         paths.ensure_layout(root)
-        launcher = bootstrap.ensure_engine()
     except CodeGraphAgentError as exc:
         error_shim.serve(exc)
         return 0
 
+    cached = bootstrap.cached_launcher()
+    if cached is not None:
+        return proxy.run(launcher=cached, cwd=root)
+
+    # Engine not cached — serve install-mode until the agent calls
+    # codegraphagent_check_engine (which triggers the download), or until
+    # shutdown / EOF.
+    launcher = install_shim.serve()
+    if launcher is None:
+        return 0
     return proxy.run(launcher=launcher, cwd=root)

tests/test_cli.py

@@ -1,4 +1,4 @@
-"""cli.main — orchestrates paths.ensure_layout → bootstrap.ensure_engine → proxy.run."""
+"""cli.main — orchestrates paths → cached_launcher → (install_shim or proxy)."""
 
 from __future__ import annotations
 
@@ -8,50 +8,83 @@
 import pytest
 
 from codegraphagent import cli
-from codegraphagent.errors import BootstrapError, LayoutConflictError
+from codegraphagent.errors import LayoutConflictError
 
 
-def test_main_happy_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+def test_main_proxies_immediately_when_engine_cached(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    """Cached engine → straight to proxy, no install_shim involvement."""
     monkeypatch.setenv("BIOROUTER_WORKING_DIR", str(tmp_path))
     (tmp_path / ".git").mkdir()
 
-    fake_launcher = tmp_path / "fake-launcher"
-    fake_launcher.write_text("")
+    cached_launcher = tmp_path / "cached-launcher"
+    cached_launcher.write_text("")
 
     proxy_run = MagicMock(return_value=0)
+    install_shim_serve = MagicMock()
 
-    with patch.object(cli.bootstrap, "ensure_engine", return_value=fake_launcher), \
-         patch.object(cli.proxy, "run", proxy_run):
+    with patch.object(cli.bootstrap, "cached_launcher", return_value=cached_launcher), \
+         patch.object(cli.proxy, "run", proxy_run), \
+         patch.object(cli.install_shim, "serve", install_shim_serve):
         rc = cli.main()
 
     assert rc == 0
+    install_shim_serve.assert_not_called()
     proxy_run.assert_called_once()
     kwargs = proxy_run.call_args.kwargs
-    assert kwargs["launcher"] == fake_launcher
+    assert kwargs["launcher"] == cached_launcher
     assert kwargs["cwd"] == tmp_path.resolve()
 
 
-def test_main_falls_back_to_error_shim_on_bootstrap_error(
+def test_main_serves_install_shim_when_not_cached_then_proxies(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ):
+    """Not cached → install_shim runs, returns a launcher, then proxy runs."""
     monkeypatch.setenv("BIOROUTER_WORKING_DIR", str(tmp_path))
     (tmp_path / ".git").mkdir()
 
-    err = BootstrapError("nope", url="https://example.com/x")
-    error_shim_serve = MagicMock()
+    installed_launcher = tmp_path / "freshly-installed"
+    installed_launcher.write_text("")
+
+    install_shim_serve = MagicMock(return_value=installed_launcher)
+    proxy_run = MagicMock(return_value=0)
 
-    with patch.object(cli.bootstrap, "ensure_engine", side_effect=err), \
-         patch.object(cli.error_shim, "serve", error_shim_serve):
+    with patch.object(cli.bootstrap, "cached_launcher", return_value=None), \
+         patch.object(cli.install_shim, "serve", install_shim_serve), \
+         patch.object(cli.proxy, "run", proxy_run):
         rc = cli.main()
 
     assert rc == 0
-    error_shim_serve.assert_called_once()
-    assert error_shim_serve.call_args.args[0] is err
+    install_shim_serve.assert_called_once()
+    proxy_run.assert_called_once()
+    assert proxy_run.call_args.kwargs["launcher"] == installed_launcher
+
+
+def test_main_exits_zero_when_install_shim_returns_none(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    """install_shim returns None (shutdown/EOF before install) → exit 0, no proxy."""
+    monkeypatch.setenv("BIOROUTER_WORKING_DIR", str(tmp_path))
+    (tmp_path / ".git").mkdir()
+
+    install_shim_serve = MagicMock(return_value=None)
+    proxy_run = MagicMock(return_value=0)
+
+    with patch.object(cli.bootstrap, "cached_launcher", return_value=None), \
+         patch.object(cli.install_shim, "serve", install_shim_serve), \
+         patch.object(cli.proxy, "run", proxy_run):
+        rc = cli.main()
+
+    assert rc == 0
+    install_shim_serve.assert_called_once()
+    proxy_run.assert_not_called()
 
 
 def test_main_falls_back_to_error_shim_on_layout_conflict(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ):
+    """Real .codegraph directory triggers LayoutConflictError → error_shim."""
     monkeypatch.setenv("BIOROUTER_WORKING_DIR", str(tmp_path))
     (tmp_path / ".git").mkdir()
     (tmp_path / ".codegraph").mkdir()

tests/test_smoke.py

@@ -19,7 +19,7 @@ def test_cli_entrypoint_runs(tmp_path, monkeypatch):
     fake_launcher = tmp_path / "fake-launcher"
     fake_launcher.write_text("")
 
-    with patch.object(cli.bootstrap, "ensure_engine", return_value=fake_launcher), \
+    with patch.object(cli.bootstrap, "cached_launcher", return_value=fake_launcher), \
          patch.object(cli.proxy, "run", MagicMock(return_value=0)):
         rc = cli.main()