fix(config): clearer error when model alias replacement starts with ^

Weighted composite routing uses ^ as a branch separator. A leading ^
creates an empty first branch and produced a generic parser message.
Validate explicitly and raise ConfigurationError with a dedicated
error_code and actionable wording. Add unit tests for leading ^ and
whitespace-prefixed ^.

Made-with: Cursor

Author: Mateusz

src/core/config/semantic_validation.py

@@ -718,6 +718,11 @@ def warn_if_alias_references_without_rules(config: AppConfig) -> None:
     )
 
 
+def _replacement_starts_with_weighted_separator(replacement: str) -> bool:
+    """True when the first composite branch would be empty (leading '^' after spaces)."""
+    return bool(replacement.lstrip().startswith("^"))
+
+
 def validate_model_aliases(config: AppConfig) -> None:
     """Validate model alias patterns and replacement routing strings at startup.
 
@@ -726,6 +731,8 @@ def validate_model_aliases(config: AppConfig) -> None:
 
     Validates:
     - Regex pattern syntax is valid.
+    - Replacement does not begin with '^' (weighted branch separator), which would
+      yield an empty first branch and a confusing parser error.
     - Replacement string is valid composite routing grammar (|, ^, [weight=N]).
     - No raw separator characters in query-param values.
     - Explicit backend names reference registered backends.
@@ -790,6 +797,25 @@ def validate_model_aliases(config: AppConfig) -> None:
                 },
             )
 
+        if _replacement_starts_with_weighted_separator(replacement):
+            raise ConfigurationError(
+                message=(
+                    f"Model alias at index {idx} has invalid replacement: it starts with '^' "
+                    f"(after optional leading whitespace). In composite weighted routing, '^' "
+                    f"separates branches; a leading '^' creates an empty first branch. "
+                    f'Write the first branch first, e.g. "[first]backend:model^..." instead of '
+                    f'"^[first]backend:model^...". '
+                    f"Alias pattern: '{pattern}'. Replacement: '{replacement}'."
+                ),
+                details={
+                    "error_code": "invalid_alias_replacement_leading_weighted_separator",
+                    "alias_index": idx,
+                    "alias_pattern": pattern,
+                    "replacement": replacement,
+                    "reason": "leading_caret_weighted_separator",
+                },
+            )
+
         routing_input = CompositeRoutingInput(
             selector=replacement,
             surface=RoutingSurface.MAIN,

tests/unit/core/config/test_model_alias_validation.py

@@ -197,6 +197,49 @@ def test_empty_branch_in_failover_raises(self):
             == "invalid_alias_replacement_syntax"
         )
 
+    def test_leading_weighted_separator_caret_raises_clear_error(self):
+        """Leading '^' creates an empty branch; surface a dedicated message."""
+        config = AppConfig(
+            model_aliases=[
+                ModelAliasRule(
+                    pattern="^alias:oss-code-medium$",
+                    replacement=(
+                        "^[first]zai-coding-plan:glm-5.1"
+                        "^[weight=4]qwen-oauth:qwen/coder-model"
+                        "^[weight=2]opencode-go:opencode-go/mimo-v2-pro"
+                    ),
+                ),
+            ],
+        )
+        with pytest.raises(ConfigurationError) as exc_info:
+            validate_model_aliases(config)
+
+        assert (
+            exc_info.value.details.get("error_code")
+            == "invalid_alias_replacement_leading_weighted_separator"
+        )
+        assert "starts with '^'" in exc_info.value.message
+        assert (
+            exc_info.value.details.get("reason") == "leading_caret_weighted_separator"
+        )
+
+    def test_leading_whitespace_before_caret_raises_same_error(self):
+        config = AppConfig(
+            model_aliases=[
+                ModelAliasRule(
+                    pattern="^x$",
+                    replacement="  ^openai:gpt-4o^anthropic:claude-3-5-sonnet",
+                ),
+            ],
+        )
+        with pytest.raises(ConfigurationError) as exc_info:
+            validate_model_aliases(config)
+
+        assert (
+            exc_info.value.details.get("error_code")
+            == "invalid_alias_replacement_leading_weighted_separator"
+        )
+
     def test_unknown_backend_raises(self):
         config = AppConfig(
             model_aliases=[