mtrx-cli 0.1.25 → 0.1.27

package/src/matrx/cli/main.py

@@ -84,6 +84,8 @@ def main(argv: list[str] | None = None) -> int:
         return 0
     if args.command == "project":
         return _cmd_project(args)
+    if args.command == "agents":
+        return _cmd_agents(args)
 
     parser.print_help()
     return 1
@@ -147,6 +149,53 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Launch Cursor after applying the current Matrx settings",
     )
 
+    # ── mtrx agents ──────────────────────────────────────────────────────────
+    agents = subparsers.add_parser("agents", help="Real-time multi-agent coordination")
+    agents_sub = agents.add_subparsers(dest="agents_command")
+
+    agents_list = agents_sub.add_parser("list", help="Show agents active in the group")
+    agents_list.add_argument("--group", metavar="GROUP_ID", help="Group to query")
+    agents_list.add_argument(
+        "--history",
+        action="store_true",
+        help="Also include recent completed activities",
+    )
+    agents_list.add_argument(
+        "--limit",
+        type=int,
+        default=10,
+        help="Max history entries to return (default: 10)",
+    )
+
+    agents_push = agents_sub.add_parser(
+        "push", help="Push a task into another agent's inbox"
+    )
+    agents_push.add_argument("target", help="Target agent ID")
+    agents_push.add_argument(
+        "prompt_parts",
+        nargs="+",
+        metavar="WORD",
+        help="Task prompt (all remaining words)",
+    )
+    agents_push.add_argument("--group", metavar="GROUP_ID", help="Override group")
+    agents_push.add_argument(
+        "--from-agent",
+        dest="from_agent",
+        metavar="AGENT_ID",
+        help="Sender identity (defaults to 'cli')",
+    )
+
+    agents_watch = agents_sub.add_parser(
+        "watch", help="Stream live group events to the terminal"
+    )
+    agents_watch.add_argument("--group", metavar="GROUP_ID", help="Group to watch")
+
+    agents_status = agents_sub.add_parser(
+        "status", help="Show this workspace's group/agent binding"
+    )
+    agents_status.add_argument("--group", metavar="GROUP_ID", help="Override group")
+    agents_status.add_argument("--agent", metavar="AGENT_ID", help="Override agent")
+
     return parser
 
 
@@ -367,8 +416,115 @@ def _run_matrx_browser_login(
     return result
 
 
+def _matrx_skip_remote_key_verify() -> bool:
+    return (os.environ.get("MTRX_SKIP_KEY_VERIFY") or "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+    }
+
+
+def _verify_matrx_key_with_server(state: dict, key: str) -> str:
+    """
+    Ping the configured Matrx API with the key.
+
+    Returns:
+        "valid" — server accepted the key (HTTP 200).
+        "invalid" — 401/403 (revoked, wrong deployment, etc.).
+        "unreachable" — network error or unexpected status (caller may proceed with a warning).
+    """
+    if _matrx_skip_remote_key_verify():
+        return "valid"
+    if not key.startswith("mx_"):
+        return "valid"
+
+    base_url = ensure_root_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+    url = f"{base_url.rstrip('/')}/v1/auth/context"
+    try:
+        with httpx.Client(timeout=12) as client:
+            resp = client.get(url, headers={"X-Matrx-Key": key})
+    except httpx.HTTPError as exc:
+        print(
+            f"[warn] Could not reach Matrx at {base_url} to verify your API key ({exc}). "
+            "Continuing; if requests fail with 403, run: mtrx login matrx --web",
+            file=sys.stderr,
+        )
+        return "unreachable"
+
+    if resp.status_code == 200:
+        return "valid"
+    if resp.status_code in (401, 403):
+        return "invalid"
+
+    print(
+        f"[warn] Matrx key check returned HTTP {resp.status_code}; continuing. "
+        "If tools fail, run: mtrx login matrx --web",
+        file=sys.stderr,
+    )
+    return "unreachable"
+
+
+def _handle_rejected_matrx_key(state: dict, key: str) -> None:
+    """
+    React to a server-rejected key. Clears saved config when appropriate, or raises
+    with instructions when the key comes from MTRX_KEY / workspace binding.
+    """
+    auth_cfg = state.setdefault("auth", {}).setdefault("matrx", {})
+    env_key = normalize_matrx_key(os.environ.get("MTRX_KEY"))
+    workspace_binding = get_workspace_binding(
+        state, cwd=os.environ.get("PWD") or os.getcwd()
+    ) or {}
+    ws_key = normalize_matrx_key(workspace_binding.get("matrx_key"))
+    saved = normalize_matrx_key(auth_cfg.get("key"))
+
+    print(
+        "Matrx rejected this API key (wrong server, revoked, expired, or not in this deployment).",
+        file=sys.stderr,
+    )
+
+    if env_key == key:
+        raise ValueError(
+            "MTRX_KEY in your environment is not valid for this Matrx server. "
+            "Unset it or set a fresh key, then run:\n"
+            "  mtrx login matrx --web\n"
+            "  # or: mtrx login matrx --key mx_..."
+        )
+    if ws_key == key:
+        raise ValueError(
+            "The Matrx key stored for this workspace is invalid for the configured server. "
+            "Run:\n"
+            "  mtrx project switch <name>\n"
+            "after signing in with: mtrx login matrx --web"
+        )
+    if saved == key:
+        auth_cfg["key"] = None
+        print(
+            "Cleared the saved Matrx key from ~/.config/mtrx (or MTRX_CONFIG_DIR).",
+            file=sys.stderr,
+        )
+        return
+
+    raise ValueError(
+        "Matrx API key was rejected. Refresh it with:\n"
+        "  mtrx login matrx --web\n"
+        "  # or: mtrx login matrx --key mx_..."
+    )
+
+
 def _complete_matrx_login(state: dict, *, force: bool = False) -> tuple[dict, bool]:
     auth_cfg = state.setdefault("auth", {}).setdefault("matrx", {})
+    if not force and _has_matrx_login(state, env=os.environ):
+        key = _resolved_matrx_key(state, os.environ)
+        if key.startswith("mx_"):
+            outcome = _verify_matrx_key_with_server(state, key)
+            if outcome == "invalid":
+                _handle_rejected_matrx_key(state, key)
+            elif outcome == "valid":
+                return state, False
+            # unreachable: already warned; treat as OK for offline / flaky networks
+        else:
+            return state, False
+
     if not force and _has_matrx_login(state, env=os.environ):
         return state, False
     if not _is_interactive_terminal():
@@ -428,14 +584,20 @@ def _maybe_promote_direct_route(state: dict, tool: str, route: str | None) -> tu
         return route, False
     if configured_route(state, tool) != "direct":
         return route, False
-    if _has_matrx_login(state, env=os.environ):
+    if state.get("explicit_direct_route", {}).get(tool):
         return route, False
+    # Matrx credentials present: align saved default with `mtrx <tool>` (same as `mtrx use <tool> matrx`).
+    if _has_matrx_login(state, env=os.environ):
+        state.setdefault("defaults", {})[tool] = "matrx"
+        state.setdefault("explicit_direct_route", {})[tool] = False
+        return "matrx", True
     if not _is_interactive_terminal():
         return route, False
 
     print(f"`mtrx {tool}` is currently configured to use the direct route.")
     if _prompt_yes_no(f"Switch {tool} to the Matrx route and continue with Matrx sign-in?", default=True):
         state.setdefault("defaults", {})[tool] = "matrx"
+        state.setdefault("explicit_direct_route", {})[tool] = False
         return "matrx", True
     return route, False
 
@@ -514,10 +676,19 @@ def _cmd_login(args) -> int:
 
 def _cmd_use(args) -> int:
     state = load_state()
-    if not _has_matrx_login(state, env=os.environ):
-        print("Login required. Run: mtrx login matrx --key mx_...", file=sys.stderr)
+    try:
+        state, login_changed = _complete_matrx_login(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
         return 1
+    if login_changed:
+        save_state(state)
     state["defaults"][args.tool] = args.route
+    explicit = state.setdefault("explicit_direct_route", {})
+    if args.route == "direct":
+        explicit[args.tool] = True
+    else:
+        explicit[args.tool] = False
     path = save_state(state)
     print(f"Default route for {args.tool}: {args.route}")
     print(f"Saved to {path}")
@@ -716,9 +887,16 @@ def _resolve_personal_policy_target(state: dict, *, key: str) -> tuple[dict, dic
 
 def _cmd_personal_optimize(args) -> int:
     state = load_state()
+    try:
+        state, login_changed = _complete_matrx_login(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if login_changed:
+        save_state(state)
     key = _personal_matrx_key(state)
     if not key:
-        print("Personal Matrx login required. Run: mtrx login matrx", file=sys.stderr)
+        print("No Matrx key available. Run: mtrx login matrx --key mx_...", file=sys.stderr)
         return 1
 
     try:
@@ -909,6 +1087,11 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
         )
         if initialized or changed or auth_changed or promoted:
             save_state(state)
+        if promoted:
+            print(
+                f"Default route for {tool} was direct — updated to matrx. "
+                f"Use `mtrx use {tool} direct` if you want to stay on the direct route.",
+            )
         if initialized:
             print(
                 f"First-time setup: default route for {tool} set to matrx. "
@@ -931,33 +1114,60 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
 
 
 def _cmd_cursor(args) -> int:
+    import json as _json
+    import subprocess
+    import time
+
+    from matrx.cli.cursor_ca import (
+        ca_cert_path,
+        ca_exists,
+        generate_ca,
+        is_ca_trusted,
+        trust_ca_system,
+        windows_trust_status,
+    )
     from matrx.cli.cursor_hooks import install_mtrx_hooks, is_mtrx_hooks_installed
-    from matrx.cli.cursor_service import is_proxy_running
-    from matrx.cli.cursor_launcher import find_cursor_executable
+    from matrx.cli.cursor_launcher import find_cursor_executable, launch_cursor_with_proxy
+    from matrx.cli.cursor_proxy import DEFAULT_PORT, PROXY_HOST
+    from matrx.cli.cursor_service import get_proxy_status, install_service, is_proxy_running, uninstall_service
 
     route = args.route
 
-    # --status: report Base URL override + hooks status
+    # --status
     if args.status:
-        state = load_state()
+        proxy_prev_path = config_dir() / "cursor-proxy-previous-settings.json"
         hooks_installed = is_mtrx_hooks_installed()
-        base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
-        prev_path = config_dir() / "cursor-previous-settings.json"
-        legacy_proxy_prev_path = config_dir() / "cursor-proxy-previous-settings.json"
-        configured = prev_path.exists()
-        legacy_proxy_active = is_proxy_running() or legacy_proxy_prev_path.exists()
+        proxy_running = is_proxy_running()
+        trust_status = windows_trust_status() if os.name == "nt" and ca_exists() else None
         print("MTRX Cursor integration:")
-        print(f"  mode: {'Base URL override (all models)' if configured else 'not configured'}")
+        print(f"  mode: {'MITM proxy (all models)' if proxy_prev_path.exists() else 'not configured'}")
+        if proxy_running:
+            status = get_proxy_status()
+            req_count = status.get("requests", "?") if status else "?"
+            print(f"  proxy: running ({PROXY_HOST}:{DEFAULT_PORT}, {req_count} requests)")
+        else:
+            print(f"  proxy: not running")
+        print(f"  ca cert: {'generated' if ca_exists() else 'not generated'} — {ca_cert_path()}")
+        if trust_status is not None:
+            print(
+                "  trust: "
+                f"user_root={'yes' if trust_status['user_root'] else 'no'}, "
+                f"machine_root={'yes' if trust_status['machine_root'] else 'no'}, "
+                f"fully_trusted={'yes' if trust_status['fully_trusted'] else 'no'}"
+            )
+        elif ca_exists():
+            print(f"  trust: {'trusted' if is_ca_trusted() else 'not trusted'}")
+        print(f"  proxy settings: {'written' if proxy_prev_path.exists() else 'not written'}")
+        print("  launch env: `mtrx cursor --launch` sets NODE_EXTRA_CA_CERTS for the launched Cursor process")
         print(f"  hooks: {'active (sessionEnd, stop → telemetry)' if hooks_installed else 'not installed'}")
-        print(f"  legacy MITM proxy: {'active' if legacy_proxy_active else 'not active'}")
-        if configured:
-            print(f"  matrx: {base_url}")
         return 0
 
-    # --stop: tear down
+    # --stop
     if args.stop:
         _restore_cursor_if_needed()
-        print("Cursor route set to direct — MTRX disabled.")
+        print("MTRX Cursor proxy stopped.")
+        if cursor_is_running():
+            print("  Restart Cursor for settings to take effect.")
         return 0
 
     state = load_state()
@@ -971,7 +1181,7 @@ def _cmd_cursor(args) -> int:
             print("  Restart Cursor for settings to take effect.")
         return 0
 
-    # --- matrx route: Base URL override (works with any Cursor model: Claude, GPT, Gemini, etc.) ---
+    # --- matrx route: MITM proxy (intercepts all Cursor traffic, any model) ---
 
     try:
         state, login_changed = _complete_matrx_login(state)
@@ -995,70 +1205,135 @@ def _cmd_cursor(args) -> int:
     matrx_base_url = ensure_root_url(
         state.get("auth", {}).get("matrx", {}).get("base_url")
     )
-    matrx_proxy_url = ensure_v1_url(matrx_base_url)
 
     if initialized or login_changed or promoted:
         save_state(state)
+    if promoted:
+        print(
+            "Default route for cursor was direct — updated to matrx. "
+            "Use `mtrx use cursor direct` if you want to stay on the direct route.",
+        )
     if initialized:
         print(
             "First-time setup: default route for cursor set to matrx. "
             "Use `mtrx use cursor direct` to opt out.",
         )
 
-    # Ensure legacy MITM routing is fully torn down before enabling the
-    # current Cursor base-URL override flow. Leaving both active causes
-    # Cursor traffic to keep flowing through the old telemetry proxy.
-    _restore_cursor_if_needed()
+    # 1. Generate CA cert if not present
+    if not ca_exists():
+        generate_ca()
+        print("MTRX CA certificate generated.")
+    cert_path = ca_cert_path()
+
+    # 2. Attempt system-wide CA trust (requires elevation on Windows/Mac)
+    trusted_before = is_ca_trusted()
+    trust_ok = trusted_before or trust_ca_system(cert_path)
+    trusted_after = trusted_before or is_ca_trusted()
+    if os.name == "nt":
+        trust_status = windows_trust_status(cert_path)
+        print(
+            "Windows trust status:"
+            f" user_root={'yes' if trust_status['user_root'] else 'no'},"
+            f" machine_root={'yes' if trust_status['machine_root'] else 'no'}"
+        )
+        if not trust_status["user_root"]:
+            print("[warn] CurrentUser Root store is missing the MTRX CA.")
+            print(f"  Run without elevation: certutil -user -addstore Root \"{cert_path}\"")
+        if not trust_status["machine_root"]:
+            print("[warn] LocalMachine Root store is missing the MTRX CA.")
+            print(f"  Run as Admin: certutil -addstore Root \"{cert_path}\"")
+        if not (trust_ok or trusted_after or trust_status["user_root"]):
+            print("[warn] The MTRX CA is not trusted by a Windows root store yet.")
+            print("  Cursor's native network stack may still reject intercepted TLS connections.")
+        elif trust_status["user_root"] and not trust_status["machine_root"]:
+            print("[warn] Current-user trust is present, but machine-wide trust is still missing.")
+            print("  Some Cursor native network paths may still reject intercepted TLS connections.")
+        print("  `mtrx cursor --launch` sets NODE_EXTRA_CA_CERTS and disables QUIC for the launched Cursor process.")
+    elif not trust_ok and not trusted_after:
+        print("[warn] The MTRX CA is not trusted by the OS certificate store yet.")
+        print("  Cursor's native network stack may still reject intercepted TLS connections.")
+        print("  On Mac:")
+        print(
+            f"    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \"{cert_path}\""
+        )
+        print("  `mtrx cursor --launch` still sets NODE_EXTRA_CA_CERTS for Node-based requests only.")
 
-    # Configure Cursor's Override Base URL — sends chat to MTRX (any model: Claude, GPT-5, Gemini, etc.)
-    prev_path = config_dir() / "cursor-previous-settings.json"
-    previous = configure_cursor_for_proxy(matrx_proxy_url, mx_key)
-    if previous is not None:
-        prev_path.write_text(__import__("json").dumps(previous), encoding="utf-8")
+    # 3. Start proxy daemon
+    if is_proxy_running():
+        print(f"MTRX proxy already running on {PROXY_HOST}:{DEFAULT_PORT}.")
     else:
-        print(
-            "[warn] Could not write Cursor state.vscdb. Try manual setup:",
-            file=sys.stderr,
+        print("Starting MTRX proxy...", end=" ", flush=True)
+        ok = install_service(
+            matrx_key=mx_key,
+            matrx_base_url=matrx_base_url,
         )
-        print_manual_setup_instructions(matrx_proxy_url, api_key_hint="your Matrx key (mx_...)")
+        if not ok:
+            # Poll a bit longer before giving up
+            for _ in range(10):
+                time.sleep(0.5)
+                if is_proxy_running():
+                    ok = True
+                    break
+        if ok:
+            print("done.")
+        else:
+            print("failed.")
+            print("[error] Proxy did not start. Check logs:", file=sys.stderr)
+            print(f"  {config_dir() / 'logs' / 'cursor-proxy.err.log'}", file=sys.stderr)
+            return 1
 
-    # Hooks for session telemetry
+    # 4. Write http.proxy + NODE_EXTRA_CA_CERTS to Cursor's settings.json (idempotent)
+    proxy_prev_path = config_dir() / "cursor-proxy-previous-settings.json"
+    if not proxy_prev_path.exists():
+        previous = configure_cursor_proxy_settings(
+            proxy_url=f"http://{PROXY_HOST}:{DEFAULT_PORT}",
+            ca_cert_path=str(cert_path),
+        )
+        proxy_prev_path.write_text(_json.dumps(previous), encoding="utf-8")
+
+    # 5. Install hooks for session telemetry
     install_mtrx_hooks(mx_key, matrx_base_url)
 
-    # Optional: launch Cursor
+    # 6. Optional: launch Cursor with NODE_EXTRA_CA_CERTS set on the process
     if getattr(args, "launch", False):
-        exe = find_cursor_executable()
-        if exe:
-            import subprocess
-            try:
-                subprocess.Popen([exe], start_new_session=True)
-                print("Launched Cursor.")
-            except Exception:
-                print("[warn] Could not launch Cursor.", file=sys.stderr)
+        launched = launch_cursor_with_proxy(
+            proxy_url=f"http://{PROXY_HOST}:{DEFAULT_PORT}",
+            ca_cert_path=str(cert_path),
+        )
+        if launched:
+            print("Launched Cursor with MTRX proxy environment.")
         else:
-            print("[warn] Could not find Cursor executable.", file=sys.stderr)
+            print("[warn] Could not find Cursor executable. Open Cursor manually.", file=sys.stderr)
 
     print()
-    print("Cursor configured for MTRX — chat routes through Matrx (all models).")
-    print(f"  base URL: {matrx_proxy_url}")
+    print("Cursor configured for MTRX — all traffic routed through MITM proxy.")
+    print(f"  proxy:    {PROXY_HOST}:{DEFAULT_PORT}")
+    print(f"  ca cert:  {cert_path}")
     print()
-    print("  Works with any Cursor Pro model: Claude, GPT-5, Gemini, and more.")
-    print("  Restart Cursor for settings to take effect.")
+    print("  Works with all Cursor Pro models: Claude, GPT, Gemini, cursor-fast, and more.")
+    if not getattr(args, "launch", False):
+        print("  Restart Cursor for settings to take effect.")
+        print("  Tip: use `mtrx cursor --launch` to open Cursor with the proxy pre-wired.")
     print("  Check status: mtrx cursor --status")
-    print("  To disable:   mtrx use cursor direct")
+    print("  To disable:   mtrx cursor --stop")
     return 0
 
 
-def _has_matrx_login(state: dict, env: dict[str, str] | None = None) -> bool:
+def _resolved_matrx_key(state: dict, env: dict[str, str] | None = None) -> str:
+    """Matrx API key from MTRX_KEY, workspace binding, or saved login (first match)."""
     env = env or {}
     env_key = normalize_matrx_key(env.get("MTRX_KEY"))
     if env_key:
-        return True
+        return env_key
     workspace_binding = get_workspace_binding(state, cwd=env.get("PWD") or os.getcwd()) or {}
     workspace_key = normalize_matrx_key(workspace_binding.get("matrx_key"))
     if workspace_key:
-        return True
-    return bool(normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key")))
+        return workspace_key
+    return normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key")) or ""
+
+
+def _has_matrx_login(state: dict, env: dict[str, str] | None = None) -> bool:
+    return bool(_resolved_matrx_key(state, env))
 
 
 def _default_route_label(route: str | None) -> str:
@@ -1069,6 +1344,27 @@ def _cmd_project(args) -> int:
     from matrx.cli.project_cmds import cmd_list, cmd_current, cmd_switch, cmd_create, cmd_init
 
     sub = getattr(args, "project_command", None)
+    if sub is None:
+        print("Usage: mtrx project <list|current|switch|create|init>", file=sys.stderr)
+        print("  list            List all projects in your org")
+        print("  current         Show active project for this workspace")
+        print("  switch <name>   Bind this workspace to a project")
+        print("  create <name>   Create a new project")
+        print("  init            Link this git repo to a Matrx project")
+        return 1
+
+    # Ensure Matrx auth before any project subcommand; trigger interactive
+    # login if needed so the user isn't forced to run `mtrx login` separately.
+    state = load_state()
+    try:
+        state, login_changed = _complete_matrx_login(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if login_changed:
+        # Persist immediately so sub-commands that call load_state() find the key.
+        save_state(state)
+
     if sub == "list":
         return cmd_list(args)
     if sub == "current":
@@ -1081,11 +1377,40 @@ def _cmd_project(args) -> int:
         return cmd_init(args)
 
     print("Usage: mtrx project <list|current|switch|create|init>", file=sys.stderr)
-    print("  list            List all projects in your org")
-    print("  current         Show active project for this workspace")
-    print("  switch <name>   Bind this workspace to a project")
-    print("  create <name>   Create a new project")
-    print("  init            Link this git repo to a Matrx project")
+    return 1
+
+
+def _cmd_agents(args) -> int:
+    from matrx.cli.agent_cmds import cmd_list, cmd_push, cmd_watch, cmd_status
+
+    sub = getattr(args, "agents_command", None)
+    if sub is None:
+        print("Usage: mtrx agents <list|push|watch|status>", file=sys.stderr)
+        print("  list   [--group ID] [--history]        Show agents active in the group")
+        print("  push   <target> <prompt> [--group ID]  Push a task into an agent's inbox")
+        print("  watch  [--group ID]                    Stream live group events")
+        print("  status [--group ID]                    Show workspace group/agent identity")
+        return 1
+
+    state = load_state()
+    try:
+        state, login_changed = _complete_matrx_login(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if login_changed:
+        save_state(state)
+
+    if sub == "list":
+        return cmd_list(args)
+    if sub == "push":
+        return cmd_push(args)
+    if sub == "watch":
+        return cmd_watch(args)
+    if sub == "status":
+        return cmd_status(args)
+
+    print("Usage: mtrx agents <list|push|watch|status>", file=sys.stderr)
     return 1
 
 

package/src/matrx/cli/state.py

@@ -49,6 +49,13 @@ DEFAULT_STATE: dict = {
         "gemini": None,
         "cursor": None,
     },
+    # True = user ran `mtrx use <tool> direct` and we should not auto-switch to matrx.
+    "explicit_direct_route": {
+        "codex": False,
+        "claude": False,
+        "gemini": False,
+        "cursor": False,
+    },
     "workspaces": {
         "bindings": {},
     },
@@ -166,6 +173,10 @@ def normalize_matrx_key(value: str | None) -> str:
     return cleaned
 
 
+def _normalize_binding_value(value: str | None) -> str:
+    return (value or "").strip()
+
+
 def ensure_v1_url(base_url: str | None) -> str:
     cleaned = _normalize_base_url(base_url).rstrip("/")
     if cleaned.endswith("/v1"):
@@ -292,6 +303,10 @@ def _merge_dicts(target: dict, source: dict) -> None:
 
 
 def _normalize_state(state: dict) -> None:
+    explicit = state.setdefault("explicit_direct_route", {})
+    for tool in ("codex", "claude", "gemini", "cursor"):
+        explicit.setdefault(tool, False)
+
     auth = state.setdefault("auth", {}).setdefault("matrx", {})
     auth["key"] = normalize_matrx_key(auth.get("key")) or None
     auth["base_url"] = _normalize_base_url(auth.get("base_url"))
@@ -309,6 +324,12 @@ def _normalize_state(state: dict) -> None:
             binding["matrx_key"] = matrx_key
         else:
             binding.pop("matrx_key", None)
+        for field in ("project_id", "group_id"):
+            cleaned = _normalize_binding_value(binding.get(field))
+            if cleaned:
+                binding[field] = cleaned
+            else:
+                binding.pop(field, None)
 
 
 def _normalize_base_url(base_url: str | None) -> str: