fix(gateway): validate TCP port range

src/opensquilla/cli/main.py

@@ -698,6 +698,9 @@ def gateway_run(
         None,
         "--port",
         "-p",
+        min=0,
+        max=65535,
+        metavar="PORT",
         help="Port to bind (default: config port, usually 18791)",
     ),
     bind: str | None = typer.Option(
@@ -772,6 +775,9 @@ def gateway_start(
         None,
         "--port",
         "-p",
+        min=0,
+        max=65535,
+        metavar="PORT",
         help="Port to bind (default: config port, usually 18791)",
     ),
     bind: str | None = typer.Option(
@@ -804,6 +810,9 @@ def gateway_status(
         None,
         "--port",
         "-p",
+        min=0,
+        max=65535,
+        metavar="PORT",
         help="Port to inspect (default: config port, usually 18791)",
     ),
     bind: str | None = typer.Option(
@@ -840,6 +849,9 @@ def gateway_stop(
         None,
         "--port",
         "-p",
+        min=0,
+        max=65535,
+        metavar="PORT",
         help="Port to stop (default: config port, usually 18791)",
     ),
     bind: str | None = typer.Option(
@@ -872,6 +884,9 @@ def gateway_restart(
         None,
         "--port",
         "-p",
+        min=0,
+        max=65535,
+        metavar="PORT",
         help="Port to restart (default: config port, usually 18791)",
     ),
     bind: str | None = typer.Option(

src/opensquilla/gateway/config.py

@@ -2338,7 +2338,7 @@ class GatewayConfig(BaseSettings):
     # precedence order (explicit kwarg/flag > OPENSQUILLA_LISTEN > OPENSQUILLA_GATEWAY_HOST
     # > default) is testable without the pydantic-settings env cache.
     host: str = "127.0.0.1"
-    port: int = 18791
+    port: int = Field(default=18791, ge=0, le=65535)
     # Resolved from installed distribution metadata (opensquilla.__version__),
     # not operator config. UI/RPC surfaces read __version__ directly, so any
     # stale value persisted in config.toml has no display effect.

tests/test_cli/test_config_set_key_validation.py

@@ -86,6 +86,19 @@ def test_a_real_key_still_prints_its_export(key: str, env_var: str) -> None:
     assert f"export {env_var}=18823" in result.stdout
 
 
+def test_invalid_port_is_not_persisted(tmp_path: Path) -> None:
+    target = _empty_config(tmp_path)
+
+    result = runner.invoke(
+        app,
+        ["config", "set", "port", "65536", "--config", str(target)],
+    )
+
+    assert result.exit_code == 2
+    assert "Invalid value for port" in result.stdout
+    assert tomllib.loads(target.read_text(encoding="utf-8")) == {}
+
+
 @pytest.mark.parametrize(
     ("key", "env_var", "value", "expected"),
     [

tests/test_cli/test_gateway_cmd.py

@@ -667,6 +667,22 @@ def fake_popen(argv, **kwargs):
     assert payload["url"] == "http://127.0.0.2:19999"
 
 
+def test_gateway_start_rejects_out_of_range_port_before_spawn(
+    tmp_path, monkeypatch
+) -> None:
+    monkeypatch.setenv("OPENSQUILLA_STATE_DIR", str(tmp_path / "home"))
+
+    def fail_popen(*_args, **_kwargs):
+        raise AssertionError("invalid port must not spawn a gateway")
+
+    monkeypatch.setattr(gateway_lifecycle.subprocess, "Popen", fail_popen)
+
+    result = runner.invoke(app, ["gateway", "start", "--port", "65536", "--json"])
+
+    assert result.exit_code == 2
+    assert "65536 is not in the range 0<=x<=65535" in result.stderr
+
+
 def test_gateway_status_uses_config_host_port_when_flags_are_omitted(
     tmp_path, monkeypatch
 ) -> None: