fix(quota): expose typed CLI error codes

Author: huangruiteng

loopx/cli_commands/quota.py

@@ -9,6 +9,7 @@
     compact_quota_monitor_poll_cli_payload,
     compact_quota_should_run_cli_payload,
 )
+from ..control_plane.quota.error_codes import quota_error_code
 from ..control_plane.quota.heartbeat_receipt import (
     fail_heartbeat_receipt,
     find_heartbeat_receipt,
@@ -493,6 +494,7 @@ def _quota_failure_payload(
             "mode": command,
             "registry": str(registry_path),
             "runtime_root": runtime_root_arg,
+            "error_code": quota_error_code(error),
             "error": str(error),
             "summary": {
                 "registered_goals": 0,
@@ -520,6 +522,7 @@ def _quota_failure_payload(
         "goal_id": args.goal_id,
         "decision": "skip",
         "should_run": False,
+        "error_code": quota_error_code(error),
         "reason": str(error),
         "state": "blocked_health",
         "waiting_on": "codex",
@@ -813,7 +816,7 @@ def handle_quota_command(
             payload = build_quota_plan(status_payload, mode=args.quota_command)
         if cache_metadata:
             payload["status_projection_cache"] = cache_metadata
-    except Exception as exc:
+    except Exception as exc:  # noqa: BLE001 - CLI fail-safe boundary; error_code is typed below.
         payload = _quota_failure_payload(
             args,
             registry_path=registry_path,

loopx/control_plane/quota/error_codes.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import json
+
+
+def quota_error_code(exc: BaseException) -> str:
+    if isinstance(exc, json.JSONDecodeError):
+        return "quota_state_invalid_json"
+    if isinstance(exc, ValueError):
+        return "quota_invalid_arguments"
+    if isinstance(exc, PermissionError):
+        return "quota_state_permission_denied"
+    if isinstance(exc, OSError):
+        return "quota_state_io_failed"
+    if isinstance(exc, KeyError):
+        return "quota_state_missing_field"
+    if isinstance(exc, TypeError):
+        return "quota_state_shape_error"
+    return "quota_unexpected_collection_error"

tests/control_plane/test_quota_error_codes.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from loopx.control_plane.quota.error_codes import quota_error_code
+
+
+@pytest.mark.parametrize(
+    ("exc", "expected"),
+    [
+        (ValueError("bad argument"), "quota_invalid_arguments"),
+        (OSError("state unavailable"), "quota_state_io_failed"),
+        (PermissionError("state denied"), "quota_state_permission_denied"),
+        (KeyError("missing"), "quota_state_missing_field"),
+        (TypeError("bad shape"), "quota_state_shape_error"),
+        (
+            json.JSONDecodeError("invalid json", "doc", 0),
+            "quota_state_invalid_json",
+        ),
+        (RuntimeError("unexpected"), "quota_unexpected_collection_error"),
+    ],
+)
+def test_quota_error_code_maps_typed_exceptions(
+    exc: BaseException,
+    expected: str,
+) -> None:
+    assert quota_error_code(exc) == expected