Skip to content

The agent that grows with you

fix(gateway): honour gateway.auto_multiplex_migration=false for the in-place multi-profile switch

Tekniumebd3f3a37374
diff --git a/gateway/run_profile_reconcile.py b/gateway/run_profile_reconcile.py
index 15fa61f2c50..6eacf64dc6f 100644
--- a/gateway/run_profile_reconcile.py
+++ b/gateway/run_profile_reconcile.py
@@ -59,6 +59,16 @@ def profile_serve_signature(home: Path) -> tuple:
return tuple(sig)
+def _added_profile_blocker(launch: Path) -> Optional[str]:
+ """Why a single-profile boot must not start multiplexing now that a second profile exists: the
+ ``gateway.auto_multiplex_migration: false`` opt-out on the default profile, else boot's preflight."""
+ from hermes_cli.gateway_migrate_guards import auto_migration_opted_out
+ from hermes_cli.gateway_multiplex_mode import AUTO_MIGRATION_OPTED_OUT_REASON, implicit_multiplex_blocker
+ if auto_migration_opted_out(launch):
+ return AUTO_MIGRATION_OPTED_OUT_REASON
+ return implicit_multiplex_blocker()
+
+
class GatewayProfileReconcileMixin:
"""Runtime reconciliation of the multiplexed served-profile set (hot add / unroute / credential-add)."""
@@ -330,24 +340,30 @@ class GatewayProfileReconcileMixin:
profile. Turns already running keep their bound scope; the launch profile's later work binds
its own scope through ``_standalone_launch_scope`` and the re-wired primary handlers. Any
other standalone verdict, or a preflight blocker now, leaves the gateway as it is; nothing is
- latched, so the next rescan or watcher tick retries once the blocker clears. True when armed."""
+ latched, so the next rescan or watcher tick retries once the blocker clears. The switch is an
+ automatic migration, so ``gateway.auto_multiplex_migration: false`` holds it back the same way
+ (re-read on every rescan: setting it back to true converges without a restart). True when armed."""
from hermes_cli.gateway_multiplex_mode import (
- SINGLE_PROFILE_REASON, MultiplexDecision, implicit_multiplex_blocker, log_multiplex_decision,
- recorded_standalone_reason)
+ AUTO_MIGRATION_OPTED_OUT_REASON, SINGLE_PROFILE_REASON, MultiplexDecision, log_multiplex_decision,
+ record_multiplex_decision, recorded_standalone_reason)
from hermes_cli.profiles import profiles_to_serve
from hermes_constants import get_default_hermes_root, get_process_hermes_home
- if recorded_standalone_reason() != SINGLE_PROFILE_REASON:
+ if recorded_standalone_reason() not in (SINGLE_PROFILE_REASON, AUTO_MIGRATION_OPTED_OUT_REASON):
return False
launch = get_process_hermes_home().resolve()
if launch != get_default_hermes_root().resolve():
return False # only the default home runs the multiplexer (``_launch_home_may_multiplex``)
if len(profiles_to_serve(multiplex=True, include_parked=True)) < 2:
return False
- blocker = await self._run_housekeeping_in_executor(implicit_multiplex_blocker)
+ blocker = await self._run_housekeeping_in_executor(_added_profile_blocker, launch)
if blocker is not None:
if blocker != self._single_profile_blocker_logged:
logger.warning("[MULTIPLEX] A new profile exists but this gateway stays standalone: %s", blocker)
self._single_profile_blocker_logged = blocker
+ if blocker == AUTO_MIGRATION_OPTED_OUT_REASON:
+ # Published so `gateway ensure` refuses the new profile naming the opt-out (Desktop shows
+ # that detail) instead of "only one profile exists".
+ record_multiplex_decision(MultiplexDecision(False, "guard", blocker))
return False
from tui_gateway.launch_profile_policy import activate_multi_profile_hosting
activate_multi_profile_hosting()
diff --git a/hermes_cli/gateway_multiplex_mode.py b/hermes_cli/gateway_multiplex_mode.py
index 8362563c801..efdf1e31677 100644
--- a/hermes_cli/gateway_multiplex_mode.py
+++ b/hermes_cli/gateway_multiplex_mode.py
@@ -27,6 +27,11 @@ logger = logging.getLogger(__name__)
SINGLE_PROFILE_REASON = "only one profile exists (nothing to multiplex)"
STANDALONE_PROFILE_REASON = "this profile is standalone (gateway.standalone: true); it serves only itself"
+#: A single-profile boot that ``gateway.auto_multiplex_migration: false`` keeps standalone once a second
+#: profile appears: the in-place switch is an automatic migration, so the opt-out holds it back.
+AUTO_MIGRATION_OPTED_OUT_REASON = (
+ "gateway.auto_multiplex_migration is false, so this gateway serves only its own profile; "
+ "run `hermes gateway migrate --multiplex` to serve every profile")
#: ``gateway.standalone: true`` is a TEMPORARY backwards-compatibility shim, not a supported topology.
#: It exists so fleets that lost per-profile gateways in the multiplex-only switch keep working while
diff --git a/tests/gateway/test_single_profile_host_serves_new_profile.py b/tests/gateway/test_single_profile_host_serves_new_profile.py
index 8df64336a58..92056461d56 100644
--- a/tests/gateway/test_single_profile_host_serves_new_profile.py
+++ b/tests/gateway/test_single_profile_host_serves_new_profile.py
@@ -114,6 +114,25 @@ async def test_a_blocked_new_profile_is_served_once_the_blocker_clears(standalon
assert result["added"] == ["coder"] and restarts == []
+async def test_auto_multiplex_migration_false_keeps_a_single_profile_boot_standalone(standalone_host):
+ """``gateway.auto_multiplex_migration: false`` on the default profile opts out of the in-place
+ switch: a second profile stays unserved by this process on the creator's signal and the watcher, and
+ setting the key back to true converges on the next rescan without a restart."""
+ runner, home, restarts = standalone_host
+ (home / "config.yaml").write_text(
+ "model: {default: m}\ngateway:\n auto_multiplex_migration: false\n", encoding="utf-8")
+ _mkprofile(home, "coder")
+ for reason in ("control-socket", "watcher"):
+ result = await runner.reconcile_served_profiles(reason=reason)
+ assert result["multiplex"] is False and result["served_profiles"] == ["default"]
+ assert not is_multiplex_active() and not runner.config.multiplex_profiles
+
+ (home / "config.yaml").write_text("model: {default: m}\n", encoding="utf-8")
+ result = await runner.reconcile_served_profiles(reason="watcher")
+ assert result["added"] == ["coder"] and is_multiplex_active() and restarts == []
+
+
def test_launch_profile_work_on_a_standalone_host_binds_its_scope_once_a_second_home_is_hosted(standalone_host):
"""Desktop's ``profiles.create`` hosts the new home before any rescan: from then on unscoped
secret reads fail closed, so the launch profile's own ``session.create`` (owner dispatch on a
diff --git a/website/docs/user-guide/multi-profile-gateways.md b/website/docs/user-guide/multi-profile-gateways.md
index 54cce5fe9ed..a2d5cee5925 100644
--- a/website/docs/user-guide/multi-profile-gateways.md
+++ b/website/docs/user-guide/multi-profile-gateways.md
@@ -1191,6 +1191,15 @@ wins over the profile's own file. It governs the **automatic** path only:
(and is the supported way to opt back in). Absent or `true` keeps the default
behaviour described above.
+The same setting covers a gateway that booted with only the default profile.
+Normally, once you create a second profile (Desktop's New Agent or
+`hermes profile create`), that gateway starts serving every profile in place,
+with no restart. With `auto_multiplex_migration: false` it keeps serving only
+its own profile, and the new profile is refused with that reason until you run
+`hermes gateway migrate --multiplex` or set the key back to `true`. The key is
+re-read on every profile rescan, so setting it back takes effect within about
+30 seconds, with no restart.
+
The explicit command is different: `hermes gateway migrate --multiplex` with
two or more profiles and **no** standalone secondary gateway still applies the
one remaining step — it sets `gateway.multiplex_profiles: true` and (re)starts