Skip to content

The agent that grows with you

fix(gateway): resolve a bare custom provider to its named entry

unsupportedpastels2c8e2e02af8c
diff --git a/agent/delegation_context.py b/agent/delegation_context.py
index ef2a465856d..6e94f8d3a93 100644
--- a/agent/delegation_context.py
+++ b/agent/delegation_context.py
@@ -133,6 +133,9 @@ def scrub_kanban_env(env: Mapping[str, str] | MutableMapping[str, str]) -> dict[
onto its scratch root and unfence the real one).
"""
cleaned = {k: v for k, v in env.items() if k not in KANBAN_ENV_KEYS}
+ # Only the gateway mints ``kanban`` sessions: a descendant ``hermes chat`` sending it is refused.
+ if cleaned.get("HERMES_SESSION_SOURCE") == "kanban":
+ del cleaned["HERMES_SESSION_SOURCE"]
inherited = str(env.get(DELEGATED_CHILD_ENV_MARKER) or "")
cleaned[DELEGATED_CHILD_ENV_MARKER] = inherited if inherited and inherited != "1" else _fenced_kanban_root()
return cleaned
diff --git a/agent/session_source.py b/agent/session_source.py
index 83f79227e27..92f7b728eca 100644
--- a/agent/session_source.py
+++ b/agent/session_source.py
@@ -12,7 +12,8 @@ from gateway.session_context import get_session_env
# one-shot child spawned from such a session inherits HERMES_SESSION_SOURCE (the terminal tool bridges the
# session env into child processes) but is NOT that conversation: labelling it ``tui``/``desktop`` lists it
# in the TUI/WebUI pickers as a resumable chat and lets ``hermes -c`` in the TUI continue it (#112550).
-# Automation sources (kanban, tool, cron, a2a, ...) are inherited on purpose.
+# Automation sources (tool, a2a, ...) are inherited on purpose; a Kanban worker's descendants drop its
+# gateway-only ``kanban`` label (delegation_context.scrub_kanban_env).
UI_TRANSPORT_SOURCES = frozenset({"tui", "desktop"})
# Finite non-interactive CLI runs (``hermes chat -q``/``--oneshot``, ``hermes -z``) get their own source so human
diff --git a/gateway/run_turn_prepare.py b/gateway/run_turn_prepare.py
index 1085f99a5a3..ecf9b87a5fb 100644
--- a/gateway/run_turn_prepare.py
+++ b/gateway/run_turn_prepare.py
@@ -276,6 +276,11 @@ class GatewayTurnPrepareMixin:
runtime = {k: v for k, v in runtime.items() if v not in (None, "")}
try:
db = self._session_db._db
+ if runtime.get("provider") == "custom":
+ # The adapter's billing class is shared by every named endpoint: resume needs the entry.
+ from hermes_cli.runtime_provider_custom import routed_custom_identity_in
+ runtime["provider"] = routed_custom_identity_in(
+ Path(db.db_path).parent, runtime.get("base_url"), model) or "custom"
row = db.get_session(session_id)
if not row:
return
diff --git a/gateway/session_mutation_model.py b/gateway/session_mutation_model.py
index 2a004869f0a..a1c8128acdc 100644
--- a/gateway/session_mutation_model.py
+++ b/gateway/session_mutation_model.py
@@ -81,11 +81,11 @@ async def prepare_model(authority, live, payload, prepared):
held = bound_route_holds(frozen.get('model'), frozen, followed, config)
# Every other route-bound key follows the profile's current route.
kept = ('api_key', 'api', 'api_key_from') if held else ()
- moved = tuple(k for k in ROUTE_BOUND_KEYS if k not in kept)
- frozen['model'] = {k: v for k, v in (frozen.get('model') or {}).items() if k not in moved}
+ route_keys = tuple(k for k in ROUTE_BOUND_KEYS if k not in kept)
+ frozen['model'] = {k: v for k, v in (frozen.get('model') or {}).items() if k not in route_keys}
# The profile's inline key and its private-secret pointer are not copied into the receipt:
# its secrets stay at the profile's own path, never re-committed under this session.
- frozen['model'].update({k: followed[k] for k in moved
+ frozen['model'].update({k: followed[k] for k in route_keys
if k in followed and k not in ('api_key', 'api', 'api_key_from')})
# The one selection shape config.yaml gets (#25106): api_mode follows the target, a context pin
# and the endpoint-bound credential fields (inline key, key_env/api_key_env) drop on a route change.
diff --git a/gateway/session_policy.py b/gateway/session_policy.py
index 434fc3a65be..c7c7a838fe9 100644
--- a/gateway/session_policy.py
+++ b/gateway/session_policy.py
@@ -89,6 +89,8 @@ _KEEP_STORED_LABEL = frozenset({'tool', 'oneshot'})
STORED_AS_LOCAL = frozenset(SURFACES) - _KEEP_STORED_LABEL
# Routing labels and the accounting placeholder: never a creating surface.
_NOT_A_SURFACE = frozenset({None, '', 'local', 'unknown'})
+# Labels only the gateway mints (session_cron, session_kanban, hosted rooms) -> agent surface.
+GATEWAY_SURFACES = {'cron': 'cron', 'kanban': 'cli', 'bot_room': 'bot_room'}
def created_surface(label):
@@ -422,10 +424,13 @@ def build_policy(params, config, *, private_secrets=None, profile_terminal=True,
if source == 'a2a':
from gateway.session_a2a import build_forward_policy
return build_forward_policy(params, config, private_secrets=private_secrets)
+ # ``desktop`` is the Desktop's surface name for the ``gui`` label (SURFACE_GROUPS): one launch.
+ source = 'gui' if source == 'desktop' else source
unknown = sorted(set(params) - CREATE_FIELDS)
if unknown or not isinstance(source, str) or source not in SURFACES:
- _refuse(f'params.{unknown[0]}' if unknown else 'source',
- 'unknown create field' if unknown else f'not a surface: {source!r}')
+ reserved = isinstance(source, str) and source in GATEWAY_SURFACES
+ _refuse(f'params.{unknown[0]}' if unknown else 'source', 'unknown create field' if unknown
+ else f'reserved for the gateway: {source!r}' if reserved else f'not a surface: {source!r}')
bad_bypass = next((name for name in BYPASS_FIELDS if name in params and type(params[name]) is not bool), None)
if bad_bypass:
_refuse(bad_bypass, 'must be a boolean')
@@ -540,13 +545,20 @@ def _with_entry_pick(params, config):
built-in in raw provider resolution, so the bare spelling would route, and be frozen, as a
different provider than the entry the profile runs (#140107). Only the held entry's bare key
is that entry (Desktop's guard). A keyed entry's display name is not; a keyless legacy
- ``custom_providers:`` entry's is (``configured_entry_key``). Other picks stay as they came.
+ ``custom_providers:`` entry's is (``configured_entry_key``). A bare ``custom`` pick is the billing
+ class a client echoed from the runtime, not a route: it names the configured entry serving its
+ endpoint/model, else (no endpoint picked) the profile's own entry. Other picks stay as they came.
"""
from gateway.session_route_identity import configured_entry_key, profile_route_identity
picked = params.get('provider')
if not isinstance(picked, str):
return params
identity = profile_route_identity(config)
+ if picked.strip().lower() == 'custom':
+ from hermes_cli.runtime_provider_custom import routed_custom_identity
+ healed = routed_custom_identity(params.get('base_url'), params.get('model'), config) or (
+ identity if identity.startswith('custom:') and 'base_url' not in params else None)
+ return {**params, 'provider': healed} if healed else params
if identity == 'auto' or picked.strip().lower() != (configured_entry_key(identity, config) or None):
return params
return {**params, 'provider': identity}
@@ -961,7 +973,7 @@ def restore_policy(data):
try:
policy = LocalSessionPolicy(**data)
from gateway.session_a2a import is_forward_policy
- surfaces = {**SURFACES, 'cron': 'cron', 'kanban': 'cli', 'bot_room': 'bot_room'}
+ surfaces = {**SURFACES, **GATEWAY_SURFACES}
if ((not is_forward_policy(policy) and
(policy.source not in surfaces or policy.platform != surfaces[policy.source]))
or not isinstance(policy.cwd, str) or not Path(policy.cwd).is_absolute()
diff --git a/gateway/session_tui_reads.py b/gateway/session_tui_reads.py
index 2dd430d3912..669a0820d42 100644
--- a/gateway/session_tui_reads.py
+++ b/gateway/session_tui_reads.py
@@ -49,6 +49,10 @@ def _status(authority, ref, live, policy, agent, arg) -> str:
provider=policy.provider if agent is None else None,
tokens=getattr(agent, 'session_total_tokens', 0) if agent is not None else None,
agent_running=running, home=authority.profile_id)
+ if fields['provider'] == 'custom': # the adapter's billing class: show the entry the session runs on
+ from hermes_cli.runtime_provider_custom import routed_custom_identity_in
+ fields['provider'] = routed_custom_identity_in(
+ authority.profile_id, getattr(agent, 'base_url', None) or policy.base_url, fields['model']) or 'custom'
project = server._project_info_for_cwd(policy.cwd)
return '\n'.join([
'Hermes TUI Status', '', *status_lines(fields, 'session_id', 'path'),
diff --git a/hermes_cli/runtime_provider_custom.py b/hermes_cli/runtime_provider_custom.py
index 908516b0b47..e77bd274e71 100644
--- a/hermes_cli/runtime_provider_custom.py
+++ b/hermes_cli/runtime_provider_custom.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import logging
import os
+from pathlib import Path
from typing import Any, Callable, Dict, Optional, Tuple
from hermes_cli.providers import custom_provider_aliases, custom_provider_slug
@@ -298,12 +299,13 @@ def codex_model_provider_id(requested_provider: str) -> Optional[str]:
# ── identity recovery (bare "custom" -> durable ``custom:<name>``) ─────────────────────────
-def _find_custom_identity(matches: Callable[[dict[str, Any]], bool]) -> Optional[str]:
+def _find_custom_identity(matches: Callable[[dict[str, Any]], bool],
+ config: Optional[dict[str, Any]] = None) -> Optional[str]:
"""First entry in ``providers:`` then legacy ``custom_providers:`` where ``matches(entry)``
- holds, as its canonical ``custom:<name>`` slug."""
+ holds, as its canonical ``custom:<name>`` slug. *config* defaults to the active profile's."""
rp = _rp()
try:
- config = rp.load_config()
+ config = rp.load_config() if config is None else config
except Exception:
return None
providers = config.get("providers")
@@ -341,26 +343,48 @@ def find_custom_provider_identity_by_model(model: str) -> Optional[str]:
:func:`find_custom_provider_identity` for persistence paths where no base_url survived the
round-trip (the session row always stores the model name)."""
target = str(model or "").strip().lower()
- if not target:
- return None
+ return _find_custom_identity(lambda entry: _entry_serves_model(entry, target)) if target else None
- def _entry_serves_model(entry: dict[str, Any]) -> bool:
- if any(_model_id_matches(entry.get(key), target) for key in ("model", "default_model")):
- return True
- models = entry.get("models")
- if isinstance(models, dict):
- return any(str(mid).strip().lower() == target for mid in models)
- if isinstance(models, list):
- return any(_model_id_matches(item.get("id") or item.get("name") if isinstance(item, dict) else item, target)
- for item in models)
- return False
- return _find_custom_identity(_entry_serves_model)
+def _entry_serves_model(entry: dict[str, Any], target: str) -> bool:
+ if any(_model_id_matches(entry.get(key), target) for key in ("model", "default_model")):
+ return True
+ models = entry.get("models")
+ if isinstance(models, dict):
+ return any(str(mid).strip().lower() == target for mid in models)
+ if isinstance(models, list):
+ return any(_model_id_matches(item.get("id") or item.get("name") if isinstance(item, dict) else item, target)
+ for item in models)
+ return False
+
+
+def routed_custom_identity(base_url: Optional[str] = None, model: Optional[str] = None,
+ config: Optional[dict[str, Any]] = None) -> Optional[str]:
+ """The configured ``custom:<name>`` entry a bare ``custom`` route (the billing class every named
+ endpoint reports) ran on. Entries may share one relay base_url, so the entry also serving
+ *model* beats the first one on that URL; without a URL the model alone names it."""
+ url = _route_key(base_url)
+ target = str(model or "").strip().lower()
+ if not url:
+ return _find_custom_identity(lambda entry: _entry_serves_model(entry, target), config) if target else None
+
+ def on_url(entry: dict[str, Any]) -> bool:
+ return _route_key(_entry_url(entry)) == url
+ return ((target and _find_custom_identity(lambda e: on_url(e) and _entry_serves_model(e, target), config))
+ or _find_custom_identity(on_url, config))
+
+
+def routed_custom_identity_in(home: Any, base_url: Optional[str] = None,
+ model: Optional[str] = None) -> Optional[str]:
+ """:func:`routed_custom_identity` against the profile at *home*: a session store names entries from
+ its own profile's config, never the ambient scope's (one gateway serves many profiles)."""
+ from hermes_cli.config_effective import load_user_config_effective
+ return routed_custom_identity(base_url, model, load_user_config_effective(Path(home) / "config.yaml"))
-def _endpoint_identity(base_url: str) -> Optional[str]:
+def _endpoint_identity(base_url: str, model: Optional[str] = None) -> Optional[str]:
"""The menu identity that owns ``base_url``: a configured entry, else the managed server."""
- identity = find_custom_provider_identity(base_url)
+ identity = routed_custom_identity(base_url, model)
if identity:
return identity
# The managed server has no custom-provider config entry. Recover its menu key
@@ -378,7 +402,7 @@ def canonical_custom_identity(*, base_url: Optional[str] = None, config_provider
endpoint first, then the ownership-checked managed server, then a configured model or
provider. Every session persistence/restore path shares this lookup."""
rp = _rp()
- identity = _endpoint_identity(base_url) if base_url else None
+ identity = _endpoint_identity(base_url, model) if base_url else None
if identity:
return identity
identity = find_custom_provider_identity_by_model(model) if model else None
diff --git a/hermes_state_sessions.py b/hermes_state_sessions.py
index a072ea5eec5..d02ececc619 100644
--- a/hermes_state_sessions.py
+++ b/hermes_state_sessions.py
@@ -725,9 +725,8 @@ class SessionSessionsMixin:
keys for the TUI/Desktop, ``gateway_runtime`` for the CLI), so a later resume recombines the
model with the provider that serves it (#79536). ``base_url``/``api_mode`` are always
replaced then (``None`` deletes): the previous provider's endpoint must not survive a switch,
- or resume sends the new provider's model to the old host. Callers without provider knowledge
- leave the stored route untouched.
- """
+ or resume sends the new provider's model to the old host; a bare ``custom`` is stored as the
+ entry it ran on. Callers without provider knowledge leave the stored route untouched."""
# Flush first: a still-queued pre-switch delta applied after this UPDATE would trip the
# first_accounted_route overwrite and resurrect the old route.
self.flush_token_counts()
@@ -735,6 +734,9 @@ class SessionSessionsMixin:
if model:
patch["model"] = model
if provider:
+ if provider == "custom": # the billing class every named endpoint reports, not a route
+ from hermes_cli.runtime_provider_custom import routed_custom_identity_in
+ provider = routed_custom_identity_in(Path(self.db_path).parent, base_url, model) or provider
route = {"provider": provider, "base_url": base_url or None, "api_mode": api_mode or None}
patch.update(route, gateway_runtime=route)
self._write_model_config_patch(
diff --git a/tests/gateway/test_bare_custom_route_identity.py b/tests/gateway/test_bare_custom_route_identity.py
new file mode 100644
index 00000000000..a5e225e52a0
--- /dev/null
+++ b/tests/gateway/test_bare_custom_route_identity.py
@@ -0,0 +1,97 @@
+"""A bare ``custom`` provider is the billing class every named endpoint reports, never a route.
+
+The gateway freezes, persists and syncs the configured ``custom:<name>`` entry it ran on: a launch
+pick echoing ``custom`` back, a ``/model`` switch persisting it, and a turn syncing the adapter's
+label. Entries sharing one relay base_url are told apart by the model they serve.
+
+Also: a profile-following session's model pick with an inline secret outside the followed
+sections, and ``--source desktop``. No endpoint is contacted.
+"""
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from tests.gateway.test_follow_profile_followups import _profile
+from tests.gateway.test_session_follow_profile_config import _owner
+
+RELAY = 'http://127.0.0.1:8080/v1'
+SIBLINGS = {'providers': {
+ 'glm': {'api': RELAY, 'key_env': 'RELAY_KEY', 'default_model': 'glm-5.3'},
+ 'deepseek': {'api': RELAY, 'key_env': 'RELAY_KEY', 'default_model': 'deepseek-v4.1-flash'}}}
+
+
+def home(monkeypatch):
+ from gateway import run
+ from hermes_constants import get_hermes_home
+ profile = get_hermes_home()
+ profile.mkdir(parents=True, exist_ok=True)
+ monkeypatch.setattr(run, '_hermes_home', profile)
+ return profile
+
+
[email protected]('pick, provider', [
+ ({}, 'custom:glm'),
+ ({'base_url': RELAY, 'model': 'deepseek-v4.1-flash'}, 'custom:deepseek'),
+], ids=['profile-entry', 'sibling-on-shared-url'])
+def test_a_bare_custom_launch_pick_freezes_the_configured_entry(tmp_path, pick, provider):
+ from gateway.session_policy import build_policy
+ config = {'model': {'default': 'glm-5.3', 'provider': 'custom:glm', 'base_url': RELAY,
+ 'key_env': 'RELAY_KEY'}, **SIBLINGS}
+ params = dict(cwd=str(tmp_path), provider='custom', **({'model': 'unlisted-model'} | pick))
+ model = build_policy(params, config).config()['model']
+ assert (model['provider'], model.get('base_url')) == (provider, RELAY)
+
+
+def test_a_bare_custom_route_is_persisted_as_its_entry(home):
+ from gateway.run_turn_prepare import GatewayTurnPrepareMixin
+ from hermes_state import SessionDB
+ (home / 'config.yaml').write_text(json.dumps(SIBLINGS))
+ db = SessionDB(db_path=home / 'state.db')
+ try:
+ for sid in ('switched', 'synced'):
+ db.create_session(sid, source='cli', model='glm-5.3')
+ # A /model switch on the gateway persists the resolved provider it got back.
+ db.update_session_model('switched', 'deepseek-v4.1-flash', 'custom', base_url=RELAY)
+ # A turn syncs the route its agent ran on, whose provider is the adapter's label.
+ agent = SimpleNamespace(model='deepseek-v4.1-flash', provider='custom', base_url=RELAY,
+ api_mode='chat_completions')
+ runner = SimpleNamespace(_session_db=SimpleNamespace(_db=db))
+ GatewayTurnPrepareMixin._sync_session_model_from_agent(runner, 'synced', agent)
+ stored = {sid: json.loads(db.get_session(sid)['model_config']) for sid in ('switched', 'synced')}
+ assert stored['switched']['provider'] == stored['switched']['gateway_runtime']['provider'] == 'custom:deepseek'
+ assert stored['synced']['gateway_runtime']['provider'] == 'custom:deepseek'
+ finally:
+ db.close()
+
+
+async def test_a_following_session_switches_model_with_an_inline_secret_outside_its_followed_sections(home):
+ from gateway.run_turn_prepare import GatewayTurnPrepareMixin
+ from gateway.session_bot import _target
+ from gateway.session_policy import policy_for_source
+ _profile(home, 'old-model', 1, 'old-key', tts={'openai': {'api_key': 'tts-key'}})
+ store, runner, authority, owner = _owner(home)
+ runner._peek_session_state = lambda key: None
+ runner._resolve_session_agent_runtime = (
+ lambda **kwargs: GatewayTurnPrepareMixin._resolve_session_agent_runtime(runner, **kwargs))
+ try:
+ ref, live, _entry = await _target(authority, owner.actor)
+ snap = authority.db.get_session(ref.session_id)
+ response = await owner.dispatch({'id': 'pick', 'method': 'session.mutate', 'params': dict(
+ session_id=ref.session_id, request_id='pick', operation='model', payload={'model': 'new-model'},
+ expected_revision=snap['runtime_revision'], expected_generation=snap['runtime_generation'])})
+ assert 'result' in response, response
+ policy = policy_for_source(runner, live.source)
+ assert policy.model == 'new-model'
+ assert policy.config(authority)['tts']['openai']['api_key'] == 'tts-key'
+ finally:
+ await owner.close()
+ store.close_all_db_handles()
+
+
+def test_source_desktop_launches_the_desktop_surface(tmp_path):
+ from gateway.session_policy import build_policy
+ policy = build_policy(dict(cwd=str(tmp_path), source='desktop'), {})
+ assert (policy.source, policy.platform) == ('gui', 'desktop')
diff --git a/tests/gateway/test_session_policy.py b/tests/gateway/test_session_policy.py
index 93f2baba691..a84cec642b0 100644
--- a/tests/gateway/test_session_policy.py
+++ b/tests/gateway/test_session_policy.py
@@ -143,6 +143,15 @@ def test_launch_options_are_frozen_and_validated(tmp_path):
build_policy(dict(cwd=str(tmp_path), **bad), cfg)
+def test_gateway_only_source_is_refused_by_name(tmp_path):
+ from gateway.session_policy import build_policy
+ from hermes_state_runtime import RuntimeStoreError
+ for label in ('kanban', 'cron', 'bot_room'):
+ with pytest.raises(RuntimeStoreError) as refused:
+ build_policy({'source': label, 'cwd': str(tmp_path)}, {})
+ assert (refused.value.field, refused.value.detail) == ('source', f'reserved for the gateway: {label!r}')
+
+
def test_provider_override_drops_the_previous_providers_route(tmp_path):
"""A provider pick is a whole-route change: folding it must not keep the profile's
endpoint/wire-protocol/credential pointers, else the new provider's key is sent to the old
diff --git a/tests/gateway/test_tui_session_reads.py b/tests/gateway/test_tui_session_reads.py
index 7f380686cd8..2d4ed39a7eb 100644
--- a/tests/gateway/test_tui_session_reads.py
+++ b/tests/gateway/test_tui_session_reads.py
@@ -59,6 +59,19 @@ async def test_tui_status_is_main_tui_status(owner):
assert '**' not in out and 'Gateway Status' not in out
+async def test_tui_status_names_the_custom_entry_a_bare_custom_agent_runs_on(owner):
+ relay = 'http://127.0.0.1:8080/v1'
+ (owner.home / 'config.yaml').write_text(
+ f'model: {{default: deepseek-v4.1-flash, provider: custom, base_url: "{relay}"}}\n'
+ f'providers:\n glm: {{api: "{relay}", default_model: glm-5.3}}\n'
+ f' deepseek: {{api: "{relay}", default_model: deepseek-v4.1-flash}}\n')
+ sid = (await owner.call('session.create', request_id='t', source='tui', cwd=str(owner.workdir)))['session_id']
+ agent = SimpleNamespace(model='deepseek-v4.1-flash', provider='custom', base_url=relay)
+ owner.authority.runner._cached_agent_for = lambda route: agent
+ assert 'Model: deepseek-v4.1-flash (custom:deepseek)' in await _exec(owner, sid, 'status')
+
+
@pytest.mark.asyncio
async def test_tui_context_is_main_live_context(owner):
sid = (await owner.call('session.create', request_id='t', source='tui', cwd=str(owner.workdir)))['session_id']
diff --git a/tests/tools/test_kanban_descendant_scope.py b/tests/tools/test_kanban_descendant_scope.py
index 35be2ba3a21..227e5a73a6e 100644
--- a/tests/tools/test_kanban_descendant_scope.py
+++ b/tests/tools/test_kanban_descendant_scope.py
@@ -86,6 +86,24 @@ def test_terminal_descendants_cannot_mutate_even_after_task_is_removed(tmp_path,
conn.close()
+def test_task_shell_does_not_inherit_the_workers_kanban_source(tmp_path, monkeypatch):
+ """``hermes chat -q`` in a task shell would send ``kanban``, a label only the gateway mints."""
+ from agent.session_source import session_source_for
+ from gateway import session_context as sc
+
+ _worker_board(tmp_path, monkeypatch)
+ monkeypatch.setattr(sc, "_session_context_engaged", False)
+ sc.reset_session_vars()
+ monkeypatch.setenv("HERMES_SESSION_SOURCE", "kanban")
+ terminal = LocalEnvironment(cwd=str(tmp_path))
+ try:
+ result = terminal.execute('echo "source=${HERMES_SESSION_SOURCE-unset}"')
+ finally:
+ terminal.cleanup()
+ assert "source=unset" in result["output"], result
+ assert session_source_for("cli") == "kanban"
+
+
def test_worker_cli_cannot_use_foreign_task_to_drop_run_scope(tmp_path, monkeypatch):
conn, own, foreign = _worker_board(tmp_path, monkeypatch)
assert "error" in json.loads(kanban_tools._handle_complete({"task_id": foreign, "summary": "no"}))
diff --git a/website/docs/developer-guide/gateway-local-sessions.md b/website/docs/developer-guide/gateway-local-sessions.md
index f8e0fd810cb..01c2a3930bb 100644
--- a/website/docs/developer-guide/gateway-local-sessions.md
+++ b/website/docs/developer-guide/gateway-local-sessions.md
@@ -87,6 +87,8 @@ listener keeps working.
(`gateway.session_policy.SURFACES`). They select the agent platforms `cli`, `tui`,
`desktop`, `acp`, `cli` and `cli`; `tool` (third-party integrations) and `oneshot`
(finite `chat -q` / `-z` runs) keep their own stored label so human pickers hide them.
+ `cron`, `kanban` and `bot_room` are minted only by the gateway; a client asking for one
+ is refused as `reserved for the gateway`.
The native local routing identity remains server-owned `Platform.LOCAL`; source never
grants messaging/native trust. Default TUI selection folds in `project`; GUI folds in
the client-surface toolsets (`project`, `desktop_ui`, `catalog`). GUI policy is