diff --git a/docs/reference/protocols/global-manager-command-v0.md b/docs/reference/protocols/global-manager-command-v0.md index 5c88889837..30c38bac06 100644 --- a/docs/reference/protocols/global-manager-command-v0.md +++ b/docs/reference/protocols/global-manager-command-v0.md @@ -104,6 +104,12 @@ Request rules: ## Source Reads +If both default runtime roots contain state, select the intended global +registry by path with `--registry`. When that registry declares a runtime, +use the registry alone so each Goal can route to its registered source. +An explicit `--runtime-root` pins Goal authority lookup to a single directory. +Use that override for diagnostics that intentionally inspect one runtime. + Implementations may read only compact LoopX control-plane surfaces: - global registry and project-local registry entries; diff --git a/loopx/paths.py b/loopx/paths.py index 9a5a41cf5a..84dc5eb3cd 100644 --- a/loopx/paths.py +++ b/loopx/paths.py @@ -236,8 +236,9 @@ def default_runtime_route() -> dict[str, object]: recommended_action = None if status == "conflict": recommended_action = ( - "Select one registry with --registry/--runtime-root; " - "inspect both roots before migration." + "Use --registry alone with a concrete registry file that declares its runtime " + "to follow the registered Goal sources. Use --runtime-root for an explicit " + "single-runtime operation. Inspect both roots before migration." ) elif status == "invalid": recommended_action = ( @@ -271,10 +272,7 @@ def select_default_runtime_root() -> Path: if route["target_registry_exists"] and route["legacy_registry_exists"] else "Both default LoopX runtime roots contain state." ) - raise ValueError( - f"{conflict} Select an explicit --registry and " - "--runtime-root; resolve the route conflict before using implicit defaults." - ) + raise ValueError(f"{conflict} {route['recommended_action']}") if route["status"] == "invalid": raise ValueError(str(route["recommended_action"])) return Path(str(route["selected_runtime_root"])) diff --git a/tests/control_plane/test_runtime_projection_explicit_route.py b/tests/control_plane/test_runtime_projection_explicit_route.py index eaf9b56171..f011810cd8 100644 --- a/tests/control_plane/test_runtime_projection_explicit_route.py +++ b/tests/control_plane/test_runtime_projection_explicit_route.py @@ -137,6 +137,41 @@ def unexpected_read(): ) == [root] +def test_default_conflict_guides_status_to_each_registered_goal_source( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys, +): + current, _legacy = _conflicting_default_roots(tmp_path, monkeypatch) + registry, _source_runtime, _state = promoted_create_fixture(tmp_path / "source") + source_payload = json.loads(registry.read_bytes()) + source_payload["goals"][0].update( + domain="software", adapter={"kind": "read_only_project_map_v0", "status": "connected-read-only"}, + ) + registry.write_text(json.dumps(source_payload), encoding="utf-8") + global_registry = _declare_target(current, registry) + global_payload = json.loads(global_registry.read_bytes()) + global_payload["common_runtime_root"] = str(current) + global_registry.write_text(json.dumps(global_payload), encoding="utf-8") + monkeypatch.delenv("LOOPX_REGISTRY", raising=False) + monkeypatch.chdir(tmp_path) + + args = ["--format", "json", "status", "--goal-id", DEFAULT_CONFLICT_GOAL] + with pytest.raises(SystemExit, match="Both default LoopX runtime roots") as conflict: + main(args) + assert main(["--registry", str(global_registry), *args]) == 0 + status = json.loads(capsys.readouterr().out) + assert status["ok"] is True and status["contract"]["errors"] == [] + + assert main(["--registry", str(global_registry), "--runtime-root", str(current), *args]) == 1 + forced = json.loads(capsys.readouterr().out) + assert forced.get("error_code") == "canonical_authority_required", forced + assert forced["authority_read"]["goal_id"] == DEFAULT_CONFLICT_GOAL + + advice = paths.default_runtime_route()["recommended_action"] + assert "Use --registry alone" in advice + assert "explicit single-runtime" in advice + assert str(conflict.value).endswith(advice) + + @pytest.mark.parametrize("missing_path_key", ["json_path", "markdown_path"]) def test_route_projection_with_missing_artifact_is_not_current( tmp_path: Path,