Merge pull request #3541 from Duang777/codex/core-experience-bug

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

Author: huangruiteng

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[
@@ -27,6 +31,79 @@
 )
 _FINE_GRAINED_PREFIX = re.compile(r"\A--fine-grained(?P<remainder>(?:\s[\s\S]*)?)\Z")
 
+_EFFECT_RUNTIME_STARTUP_REMEDIATION_BY_CODE = {
+    "node_unavailable": (
+        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`."
+    ),
+    "startup_lock_timeout": (
+        "Another LoopX TypeScript control-plane runtime may be starting. Run "
+        "`loopx doctor --deep`, wait for the active startup to settle, and retry "
+        "`loopx start-goal --guided`."
+    ),
+    "runtime_launch_failed": (
+        "Run `loopx doctor --deep` and retry `loopx start-goal --guided`. If the "
+        "runtime still cannot start, repair or reinstall LoopX."
+    ),
+    "runtime_exited_before_ready": (
+        "Run `loopx doctor --deep` and retry `loopx start-goal --guided`. If the "
+        "runtime exits again, repair or reinstall LoopX."
+    ),
+    "runtime_startup_timeout": (
+        "Run `loopx doctor --deep` and retry `loopx start-goal --guided`. If "
+        "startup continues to time out, repair or reinstall LoopX."
+    ),
+    "runtime_request_failed": (
+        "Run `loopx doctor --deep` and retry `loopx start-goal --guided`. If "
+        "requests continue to fail, repair or reinstall LoopX."
+    ),
+}
+_EFFECT_RUNTIME_STARTUP_DEFAULT_REMEDIATION = (
+    "Run `loopx doctor --deep` and retry `loopx start-goal --guided`. If the "
+    "TypeScript control-plane runtime remains unavailable, repair or reinstall LoopX."
+)
+
+
+def _effect_runtime_startup_recommended_action(diagnostic_code: str) -> str:
+    return _EFFECT_RUNTIME_STARTUP_REMEDIATION_BY_CODE.get(
+        diagnostic_code,
+        _EFFECT_RUNTIME_STARTUP_DEFAULT_REMEDIATION,
+    )
+
+
+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": _effect_runtime_startup_recommended_action(
+            diagnostic_code
+        ),
+    }
+
+
+def _render_start_goal_markdown(payload: dict[str, object]) -> str:
+    if payload.get("ok") is not False:
+        return render_start_goal_guided_markdown(payload)
+    lines = ["# Guided Start Goal", "", f"- error: `{payload.get('error')}`"]
+    for field in ("diagnostic_code", "recommended_action", "suggested_command"):
+        value = payload.get(field)
+        if not value:
+            continue
+        rendered = value if field == "recommended_action" else f"`{value}`"
+        lines.append(f"- {field}: {rendered}")
+    return "\n".join(lines) + "\n"
+
 
 def add_capability_route_argument(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
@@ -203,7 +280,7 @@ def handle_start_goal_command(
             "error": "`loopx start-goal` currently requires --guided",
             "suggested_command": "loopx start-goal --guided --goal-text '<goal text>'",
         }
-        print_payload(payload, args.format, render_start_goal_guided_markdown)
+        print_payload(payload, args.format, _render_start_goal_markdown)
         return 2
     try:
         goal_text, capability_route, fine_grained = _resolve_start_goal_input(args)
@@ -217,39 +294,49 @@ def handle_start_goal_command(
                 "--slash-command-arguments='<exact /loopx arguments>'"
             ),
         }
-        print_payload(payload, args.format, render_start_goal_guided_markdown)
+        print_payload(payload, args.format, _render_start_goal_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),
+                runtime_root_arg=runtime_root_arg,
+            )
+        except EffectRuntimeStartupError as exc:
+            payload = _effect_runtime_startup_failure_payload(exc)
+            print_payload(payload, args.format, _render_start_goal_markdown)
+            return 1
+        print_payload(payload, args.format, _render_start_goal_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),
             runtime_root_arg=runtime_root_arg,
         )
-        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),
-        runtime_root_arg=runtime_root_arg,
-    )
-    print_payload(payload, args.format, render_start_goal_guided_markdown)
+    except EffectRuntimeStartupError as exc:
+        payload = _effect_runtime_startup_failure_payload(exc)
+        print_payload(payload, args.format, _render_start_goal_markdown)
+        return 1
+    print_payload(payload, args.format, _render_start_goal_markdown)
     return 0

loopx/control_plane/effect_runtime.py

@@ -291,9 +291,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
 
@@ -606,28 +607,29 @@ 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,
                 method=method,
                 params=params,
                 timeout=timeout,
             )
-        except EffectRuntimeRejected:
-            raise
-        except EffectRuntimeRemoteError:
+        except (EffectRuntimeRemoteError, 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,122 @@ def _invoke_ark_start_goal_cli(
     return exit_code, payload
 
 
+def _block_effect_runtime_startup(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    diagnostic_code: str = "node_unavailable",
+) -> None:
+    def unavailable(*_args: object, **_kwargs: object) -> object:
+        raise effect_runtime.EffectRuntimeStartupError(
+            "TypeScript Effect runtime could not serve the request",
+            diagnostic_code=diagnostic_code,
+        )
+
+    monkeypatch.setattr(
+        command_pack_module,
+        "effect_program_from_ordered_steps",
+        unavailable,
+    )
+
+
+@pytest.mark.parametrize(
+    ("diagnostic_code", "expected_action_fragment", "mentions_node_installation"),
+    [
+        ("node_unavailable", "Install or activate Node.js", True),
+        (
+            "startup_lock_timeout",
+            "wait for the active startup to settle",
+            False,
+        ),
+        ("runtime_launch_failed", "runtime still cannot start", False),
+        ("runtime_exited_before_ready", "runtime exits again", False),
+        ("runtime_startup_timeout", "startup continues to time out", False),
+        ("runtime_request_failed", "requests continue to fail", False),
+        ("future_runtime_diagnostic", "runtime remains unavailable", False),
+    ],
+)
+def test_cli_reports_effect_runtime_startup_failure_without_traceback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    diagnostic_code: str,
+    expected_action_fragment: str,
+    mentions_node_installation: bool,
+) -> None:
+    project = _write_connected_project(tmp_path)
+    _block_effect_runtime_startup(monkeypatch, diagnostic_code=diagnostic_code)
+
+    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"] == diagnostic_code
+    assert payload["runtime_requirement"]["minimum_node_version"] == "22.6.0"
+    assert "loopx doctor --deep" in payload["recommended_action"]
+    assert expected_action_fragment in payload["recommended_action"]
+    assert ("Node.js" in payload["recommended_action"]) is mentions_node_installation
+    if not mentions_node_installation:
+        assert "Install or activate Node.js" not 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

@@ -87,6 +87,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: