From 5b857201b7a2a38db12b0b91d97ef35a3d00cc36 Mon Sep 17 00:00:00 2001
From: xxxigm <tuancanhnguyen706@gmail.com>
Date: Sat, 13 Jun 2026 07:22:51 +0700
Subject: [PATCH] fix(profiles): correct misleading per-profile gateway port
 docstrings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The s6 profile-gateway docstrings claimed the bind port comes from a
`[gateway] port` key in config.yaml ("the single source of truth"). No such
key exists or is read anywhere — the API server port is resolved by
gateway/config.py from `API_SERVER_PORT` (or `platforms.api_server.extra.port`)
and defaults to 8642. The wrong reference actively misled a Docker user into
setting a non-functional `gateway.port`.

Point both docstrings (`S6ServiceManager._render_run_script`,
`_maybe_register_gateway_service`) at the real knob, and note the practical
consequence: since each supervised profile gateway loads its own HERMES_HOME,
two profiles left at the default both try to bind 8642 — each needs a distinct
`API_SERVER_PORT` in its own `.env`.
---
 hermes_cli/profiles.py        | 14 ++++++++++----
 hermes_cli/service_manager.py | 23 ++++++++++++++---------
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py
index 50e5bbeabbc..b1bec337e44 100644
--- a/hermes_cli/profiles.py
+++ b/hermes_cli/profiles.py
@@ -1190,10 +1190,16 @@ def _maybe_register_gateway_service(profile_name: str) -> None:
     can re-register manually later via the gateway start command,
     which goes through the same dispatch path.
 
-    Port selection is governed by the profile's ``config.yaml``
-    (``[gateway] port = …``) — there is no Python-side allocator
-    (PR #30136 review item I5 retired the SHA-256-derived range
-    [9200, 9800) because it was dead code through the entire stack).
+    Port selection: each supervised profile gateway loads its own
+    ``HERMES_HOME`` and binds the port resolved by ``gateway/config.py``
+    from that profile's environment — ``API_SERVER_PORT`` (or
+    ``platforms.api_server.extra.port`` in the profile's
+    ``config.yaml``), defaulting to 8642. There is no ``[gateway] port``
+    key and no Python-side allocator (PR #30136 review item I5 retired
+    the SHA-256-derived range [9200, 9800) as dead code), so two
+    profiles that both leave the port at its default will both try to
+    bind 8642 — give each profile a distinct ``API_SERVER_PORT`` in its
+    ``.env``.
 
     Host short-circuit: check ``detect_service_manager()`` first and
     return immediately if it isn't ``"s6"``. This keeps host
diff --git a/hermes_cli/service_manager.py b/hermes_cli/service_manager.py
index 254c34fc17f..6e2b60c0228 100644
--- a/hermes_cli/service_manager.py
+++ b/hermes_cli/service_manager.py
@@ -585,15 +585,20 @@ class S6ServiceManager:
         would instead look up ``$HERMES_HOME/profiles/default/`` — a
         completely different (and almost always nonexistent) profile.
 
-        Port selection: the gateway picks its bind port from the
-        profile's ``config.yaml`` (``[gateway] port = ...``) — that
-        is the single source of truth. Previously this method took a
-        ``port`` parameter that was passed in but never substituted
-        into the rendered script (it was carried in for "API parity"
-        with a deterministic SHA-256 allocator in
-        ``hermes_cli.profiles._allocate_gateway_port``). PR #30136
-        review item I5 retired both the allocator and the parameter
-        because they were dead code through the entire stack.
+        Port selection: the gateway binds the port resolved by
+        ``gateway/config.py`` from the profile's own environment —
+        ``API_SERVER_PORT`` (or ``platforms.api_server.extra.port`` in
+        that profile's ``config.yaml``), defaulting to 8642. There is
+        no ``[gateway] port`` key and no Python-side allocator: because
+        each supervised profile gateway loads its own ``HERMES_HOME``,
+        two profiles that both leave the port unset will both try to
+        bind 8642 — give each profile a distinct ``API_SERVER_PORT`` in
+        its ``.env``. Previously this method took a ``port`` parameter
+        that was passed in but never substituted into the rendered
+        script (carried for "API parity" with a deterministic SHA-256
+        allocator in ``hermes_cli.profiles._allocate_gateway_port``).
+        PR #30136 review item I5 retired both the allocator and the
+        parameter because they were dead code through the entire stack.
         """
         import shlex
         lines = [