fix(cli): report start-goal runtime startup failures

Signed-off-by: duang777 <duangjl007@gmail.com>

Author: Duang777

loopx/bootstrap_command_pack.py

@@ -1698,6 +1698,23 @@ def rerun_start_goal(selected_agent_id: str) -> str:
 
 
 def render_start_goal_guided_markdown(payload: dict[str, Any]) -> str:
+    if payload.get("ok") is False:
+        lines = [
+            "# Guided Start Goal",
+            "",
+            f"- error: `{payload.get('error')}`",
+        ]
+        diagnostic_code = payload.get("diagnostic_code")
+        if diagnostic_code:
+            lines.append(f"- diagnostic_code: `{diagnostic_code}`")
+        recommended_action = payload.get("recommended_action")
+        if recommended_action:
+            lines.append(f"- recommended_action: {recommended_action}")
+        suggested_command = payload.get("suggested_command")
+        if suggested_command:
+            lines.append(f"- suggested_command: `{suggested_command}`")
+        return "\n".join(lines) + "\n"
+
     def command_summary(value: Any) -> str:
         parts = str(value or "").split()
         return " ".join(parts[:3]) + (" ..." if len(parts) > 3 else "")

loopx/cli_commands/start_goal.py

@@ -12,6 +12,10 @@
     build_start_goal_host_surface_selection_packet,
     render_start_goal_guided_markdown,
 )
+from ..control_plane.effect_runtime import (
+    EffectRuntimeStartupError,
+    MINIMUM_NODE_VERSION_TEXT,
+)
 from ._host_thread import current_host_thread_id
 
 PrintPayload = Callable[
@@ -28,6 +32,28 @@
 _FINE_GRAINED_PREFIX = re.compile(r"\A--fine-grained(?P<remainder>(?:\s[\s\S]*)?)\Z")
 
 
+def _effect_runtime_startup_failure_payload(
+    exc: EffectRuntimeStartupError,
+) -> dict[str, object]:
+    diagnostic_code = getattr(exc, "diagnostic_code", "runtime_startup_failed")
+    return {
+        "ok": False,
+        "schema_version": "loopx_start_goal_guided_v0",
+        "error": "LoopX TypeScript control-plane runtime is unavailable",
+        "diagnostic_code": diagnostic_code,
+        "runtime_requirement": {
+            "runtime": "node",
+            "minimum_node_version": MINIMUM_NODE_VERSION_TEXT,
+            "required_for": ["start-goal", "control_plane"],
+        },
+        "recommended_action": (
+            f"Install or activate Node.js {MINIMUM_NODE_VERSION_TEXT} or newer "
+            "on PATH, then run `loopx doctor --deep` and retry "
+            "`loopx start-goal --guided`."
+        ),
+    }
+
+
 def add_capability_route_argument(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--capability-route",
@@ -218,34 +244,44 @@ def handle_start_goal_command(
         print_payload(payload, args.format, render_start_goal_guided_markdown)
         return 2
     if not args.host_surface:
-        payload = build_start_goal_host_surface_selection_packet(
+        try:
+            payload = build_start_goal_host_surface_selection_packet(
+                project=Path(args.project),
+                goal_id=args.goal_id,
+                agent_id=args.agent_id,
+                thread_id=current_host_thread_id(args),
+                new_peer=bool(getattr(args, "new_peer", False)),
+                cli_bin=args.cli_bin,
+                goal_text=goal_text,
+                available_capabilities=args.available_capabilities,
+                capability_route=capability_route,
+                fine_grained=fine_grained,
+                include_command_pack_detail=bool(args.include_command_pack_detail),
+            )
+        except EffectRuntimeStartupError as exc:
+            payload = _effect_runtime_startup_failure_payload(exc)
+            print_payload(payload, args.format, render_start_goal_guided_markdown)
+            return 1
+        print_payload(payload, args.format, render_start_goal_guided_markdown)
+        return 0
+    try:
+        payload = build_start_goal_guided_packet(
             project=Path(args.project),
             goal_id=args.goal_id,
             agent_id=args.agent_id,
             thread_id=current_host_thread_id(args),
             new_peer=bool(getattr(args, "new_peer", False)),
             cli_bin=args.cli_bin,
+            host_surface=args.host_surface,
             goal_text=goal_text,
             available_capabilities=args.available_capabilities,
             capability_route=capability_route,
             fine_grained=fine_grained,
             include_command_pack_detail=bool(args.include_command_pack_detail),
         )
+    except EffectRuntimeStartupError as exc:
+        payload = _effect_runtime_startup_failure_payload(exc)
         print_payload(payload, args.format, render_start_goal_guided_markdown)
-        return 0
-    payload = build_start_goal_guided_packet(
-        project=Path(args.project),
-        goal_id=args.goal_id,
-        agent_id=args.agent_id,
-        thread_id=current_host_thread_id(args),
-        new_peer=bool(getattr(args, "new_peer", False)),
-        cli_bin=args.cli_bin,
-        host_surface=args.host_surface,
-        goal_text=goal_text,
-        available_capabilities=args.available_capabilities,
-        capability_route=capability_route,
-        fine_grained=fine_grained,
-        include_command_pack_detail=bool(args.include_command_pack_detail),
-    )
+        return 1
     print_payload(payload, args.format, render_start_goal_guided_markdown)
     return 0

loopx/control_plane/effect_runtime.py

@@ -98,9 +98,10 @@ def _runtime_server_path() -> Path:
 def _node_executable() -> str:
     status, executable, _version = _probe_node()
     if status != "ready" or executable is None:
-        raise RuntimeError(
+        raise EffectRuntimeStartupError(
             f"LoopX Effect runtime requires Node.js {MINIMUM_NODE_VERSION_TEXT} "
-            "or newer"
+            "or newer",
+            diagnostic_code="node_unavailable",
         )
     return executable
 
@@ -373,10 +374,10 @@ def effect_runtime_request(
     request_id = str(uuid.uuid4())
     last_error: OSError | RuntimeError | None = None
     for attempt in range(2 if retry_safe else 1):
-        info = _read_info(info_path, fingerprint=fingerprint)
-        if info is None:
-            info = _start_runtime(fingerprint=fingerprint, info_path=info_path)
         try:
+            info = _read_info(info_path, fingerprint=fingerprint)
+            if info is None:
+                info = _start_runtime(fingerprint=fingerprint, info_path=info_path)
             return _request_with_info(
                 info,
                 request_id=request_id,
@@ -386,13 +387,18 @@ def effect_runtime_request(
             )
         except EffectRuntimeRejected:
             raise
+        except EffectRuntimeStartupError:
+            raise
         except (OSError, RuntimeError) as exc:
             last_error = exc
             if attempt == 0 and retry_safe:
                 info_path.unlink(missing_ok=True)
                 continue
             break
-    raise RuntimeError("TypeScript Effect runtime request failed") from last_error
+    raise EffectRuntimeStartupError(
+        "TypeScript Effect runtime request failed",
+        diagnostic_code="runtime_request_failed",
+    ) from last_error
 
 
 def effect_runtime_result(

tests/control_plane/test_start_goal_compact_projection.py

@@ -10,6 +10,7 @@
 
 import pytest
 
+import loopx.bootstrap_command_pack as command_pack_module
 from loopx.bootstrap_command_pack import (
     GUIDED_COMMAND_PACK_PROJECTION_SCHEMA_VERSION,
     build_loopx_bootstrap_command_pack,
@@ -25,6 +26,7 @@
     validate_shared_todo_options,
     validate_todo_add_options,
 )
+from loopx.control_plane import effect_runtime
 
 GOAL_ID = "guided-projection-goal"
 AGENT_ID = "codex-guided-projection"
@@ -147,6 +149,95 @@ def _invoke_ark_start_goal_cli(
     return exit_code, payload
 
 
+def _block_effect_runtime_startup(monkeypatch: pytest.MonkeyPatch) -> None:
+    def unavailable(*_args: object, **_kwargs: object) -> object:
+        raise effect_runtime.EffectRuntimeStartupError(
+            "LoopX Effect runtime requires Node.js 22.6.0 or newer",
+            diagnostic_code="node_unavailable",
+        )
+
+    monkeypatch.setattr(
+        command_pack_module,
+        "effect_program_from_ordered_steps",
+        unavailable,
+    )
+
+
+def test_cli_reports_effect_runtime_startup_failure_without_traceback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    project = _write_connected_project(tmp_path)
+    _block_effect_runtime_startup(monkeypatch)
+
+    output = io.StringIO()
+    with contextlib.redirect_stdout(output):
+        exit_code = cli_main(
+            [
+                "--format",
+                "json",
+                "start-goal",
+                "--guided",
+                "--project",
+                str(project),
+                "--goal-id",
+                GOAL_ID,
+                "--agent-id",
+                AGENT_ID,
+                "--host-surface",
+                "shell",
+                "--goal-text",
+                GOAL_TEXT,
+            ]
+        )
+
+    raw_output = output.getvalue()
+    payload = json.loads(raw_output)
+    assert exit_code == 1
+    assert payload["ok"] is False
+    assert payload["schema_version"] == "loopx_start_goal_guided_v0"
+    assert payload["error"] == "LoopX TypeScript control-plane runtime is unavailable"
+    assert payload["diagnostic_code"] == "node_unavailable"
+    assert payload["runtime_requirement"]["minimum_node_version"] == "22.6.0"
+    assert "loopx doctor --deep" in payload["recommended_action"]
+    assert "Traceback" not in raw_output
+
+
+def test_cli_reports_effect_runtime_startup_failure_in_default_markdown(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    project = _write_connected_project(tmp_path)
+    _block_effect_runtime_startup(monkeypatch)
+
+    output = io.StringIO()
+    with contextlib.redirect_stdout(output):
+        exit_code = cli_main(
+            [
+                "start-goal",
+                "--guided",
+                "--project",
+                str(project),
+                "--goal-id",
+                GOAL_ID,
+                "--agent-id",
+                AGENT_ID,
+                "--host-surface",
+                "shell",
+                "--goal-text",
+                GOAL_TEXT,
+            ]
+        )
+
+    raw_output = output.getvalue()
+    assert exit_code == 1
+    assert "# Guided Start Goal" in raw_output
+    assert "LoopX TypeScript control-plane runtime is unavailable" in raw_output
+    assert "diagnostic_code: `node_unavailable`" in raw_output
+    assert "loopx doctor --deep" in raw_output
+    assert "Traceback" not in raw_output
+
+
 def test_default_projection_preserves_host_actions_and_json_anchors(
     tmp_path: Path,
 ) -> None:

tests/control_plane/test_turn_journal_runtime_readiness.py

@@ -54,6 +54,20 @@ def test_missing_node_blocks_the_typescript_control_plane_and_is_actionable(
     assert "Node.js 22.6.0 or newer" in str(result["recommended_action"])
 
 
+def test_missing_node_request_raises_startup_diagnostic(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(effect_runtime, "_runtime_dir", lambda: tmp_path)
+    monkeypatch.setattr(effect_runtime.shutil, "which", lambda _name: None)
+
+    with pytest.raises(effect_runtime.EffectRuntimeStartupError) as error:
+        effect_runtime.effect_runtime_result("runtime.ping", {})
+
+    assert error.value.diagnostic_code == "node_unavailable"
+    assert "Node.js 22.6.0 or newer" in str(error.value)
+
+
 def test_old_node_is_reported_without_running_semantic_probe(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: