refactor: unify component naming — control_plane/control_auth -> orchestrator

The codebase used "control plane" both as an architectural role term AND
as an identifier alias for the orchestrator component, producing
duplicate names for one thing (control_plane_url vs orchestrator_url,
CONTROL_PLANE_PORT, host_control_plane_token, …). Going forward the
concrete component is always named for what it is — Gateway or
Orchestrator — and the plane vocabulary is reserved for prose (module
descriptions, the security argument).

Renamed (identifiers + the in-repo env/wire/file string values, all
setters/getters are in this repo so the change is atomic):

  ControlPlaneServer            -> OrchestratorServer
  control_plane_url             -> orchestrator_url
  probe_control_plane_url       -> probe_orchestrator_url
  host_control_plane_token      -> host_orchestrator_token
  CONTROL_PLANE_PORT            -> ORCHESTRATOR_PORT
  CONTROL_PLANE_TOKEN_ENV/FILE  -> ORCHESTRATOR_TOKEN_ENV/FILENAME
  BOT_BOTTLE_CONTROL_PLANE_TOKEN-> BOT_BOTTLE_ORCHESTRATOR_TOKEN
  control-plane-token (file)    -> orchestrator-token

  control_auth (module)         -> orchestrator_auth  (stays top-level;
                                   the gateway imports it and must not
                                   import the orchestrator/ package)
  CONTROL_AUTH_HEADER           -> ORCHESTRATOR_AUTH_HEADER
  x-bot-bottle-control-auth     -> x-bot-bottle-orchestrator-auth
  CONTROL_AUTH_JWT_ENV          -> ORCHESTRATOR_AUTH_JWT_ENV
  BOT_BOTTLE_CONTROL_AUTH_JWT   -> BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT
  _control_auth_headers         -> _orchestrator_auth_headers

Prose plane-terms ("control plane", "data plane") are preserved,
including the test name test_data_plane_daemons_get_jwt_not_key (it
names the security invariant). Gateway and orchestrator verified to
agree on the renamed wire header; full unit suite green (2243).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/integration/test_orchestrator_docker_auth.py

@@ -25,10 +25,10 @@ import tempfile
 import unittest
 from pathlib import Path
 
-from bot_bottle.control_auth import ROLE_CLI, ROLE_GATEWAY, mint
+from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY, mint
 from bot_bottle.orchestrator.client import OrchestratorClient
 from bot_bottle.backend.docker.infra import DockerInfraService
-from bot_bottle.paths import host_control_plane_token
+from bot_bottle.paths import host_orchestrator_token
 from tests._docker import skip_unless_docker
 
 # Fixed (not per-run-suffixed) so repeated runs reuse the same layer-cached
@@ -46,20 +46,20 @@ _TEST_INFRA_IMAGE = "bot-bottle-infra:itest"
     "runner's /workspace — same host-bind-mount constraint as the other "
     "bottle-bringup integration tests",
 )
-class TestDockerControlPlaneAuthIntegration(unittest.TestCase):
+class TestDockerOrchestratorAuthIntegration(unittest.TestCase):
     @classmethod
     def setUpClass(cls) -> None:
         suffix = secrets.token_hex(4)
         cls._tmp = tempfile.TemporaryDirectory()  # pylint: disable=consider-using-with
         cls.addClassCleanup(cls._tmp.cleanup)
 
-        # host_control_plane_token() — both the token read below and the one
+        # host_orchestrator_token() — both the token read below and the one
         # DockerInfraService injects into the container's env — resolves its
         # path via the *ambient* BOT_BOTTLE_ROOT env var, not the host_root
         # kwarg passed to the constructor (that kwarg only controls the DB
         # bind-mount destination). Without pointing the env var at the same
         # throwaway dir, this "isolated" test would read/write the developer's
-        # real ~/.bot-bottle/control-plane-token.
+        # real ~/.bot-bottle/orchestrator-token.
         previous_root = os.environ.get("BOT_BOTTLE_ROOT")
 
         def _restore_root() -> None:
@@ -88,7 +88,7 @@ class TestDockerControlPlaneAuthIntegration(unittest.TestCase):
         cls.svc.ensure_running()
         # The control plane now verifies role-scoped signed tokens, not the raw
         # key. Mint one of each role from the host signing key (issue #469 review).
-        signing_key = host_control_plane_token()
+        signing_key = host_orchestrator_token()
         cls.cli_token = mint(ROLE_CLI, signing_key)
         cls.gateway_token = mint(ROLE_GATEWAY, signing_key)
 

tests/unit/test_backend_selection.py

@@ -408,7 +408,7 @@ class TestEnsureOrchestrator(unittest.TestCase):
         with patch(
             "bot_bottle.backend.firecracker.infra_vm.ensure_running"
         ) as ensure_running:
-            ensure_running.return_value.control_plane_url = (
+            ensure_running.return_value.orchestrator_url = (
                 "http://10.243.255.1:8099"
             )
             url = b.ensure_orchestrator()
@@ -419,7 +419,7 @@ class TestEnsureOrchestrator(unittest.TestCase):
         with patch(
             "bot_bottle.backend.macos_container.infra.MacosInfraService"
         ) as service_cls:
-            service_cls.return_value.ensure_running.return_value.control_plane_url = (
+            service_cls.return_value.ensure_running.return_value.orchestrator_url = (
                 "http://192.168.128.2:8099"
             )
             url = b.ensure_orchestrator()

tests/unit/test_firecracker_infra_vm.py

@@ -31,7 +31,7 @@ class TestSigningKeySync(unittest.TestCase):
                     patch.object(infra_vm, "bot_bottle_root", return_value=root):
                 out = infra_vm._with_signing_key(self._infra())
             self.assertIsInstance(out, infra_vm.InfraVm)  # returned for chaining
-            token = root / infra_vm.CONTROL_PLANE_TOKEN_FILENAME
+            token = root / infra_vm.ORCHESTRATOR_TOKEN_FILENAME
             self.assertEqual("the-signing-key", token.read_text())
             self.assertEqual(0o600, token.stat().st_mode & 0o777)
             # It cat'd the guest volume path over SSH.
@@ -44,16 +44,16 @@ class TestSigningKeySync(unittest.TestCase):
             with patch.object(infra_vm.subprocess, "run", return_value=proc), \
                     patch.object(infra_vm, "bot_bottle_root", return_value=root):
                 infra_vm._with_signing_key(self._infra())  # no raise
-            self.assertFalse((root / infra_vm.CONTROL_PLANE_TOKEN_FILENAME).exists())
+            self.assertFalse((root / infra_vm.ORCHESTRATOR_TOKEN_FILENAME).exists())
 
 
-class TestControlPlaneUrl(unittest.TestCase):
+class TestOrchestratorUrl(unittest.TestCase):
     def test_url_uses_guest_ip_and_port(self):
         infra = infra_vm.InfraVm(
             vm=MagicMock(), guest_ip="10.243.255.1", private_key=Path("/k"))
         self.assertEqual(
-            f"http://10.243.255.1:{infra_vm.CONTROL_PLANE_PORT}",
-            infra.control_plane_url,
+            f"http://10.243.255.1:{infra_vm.ORCHESTRATOR_PORT}",
+            infra.orchestrator_url,
         )
 
 
@@ -81,11 +81,11 @@ class TestBuildInfraRootfs(unittest.TestCase):
         # Role-scoped control-plane auth (issue #469 review): the orchestrator
         # gets the signing key, the gateway daemons get a pre-minted `gateway`
         # JWT — never open mode in the infra VM.
-        self.assertIn("host_control_plane_token", init)  # key generated on the volume
+        self.assertIn("host_orchestrator_token", init)  # key generated on the volume
         self.assertIn("mint, ROLE_GATEWAY", init)         # gateway JWT minted from it
-        self.assertIn('BOT_BOTTLE_CONTROL_PLANE_TOKEN="$CP_KEY" python3 -m bot_bottle.orchestrator',
+        self.assertIn('BOT_BOTTLE_ORCHESTRATOR_TOKEN="$CP_KEY" python3 -m bot_bottle.orchestrator',
                       init)  # key -> orchestrator only
-        self.assertIn('BOT_BOTTLE_CONTROL_AUTH_JWT="$GW_JWT"', init)  # JWT -> gateway daemons
+        self.assertIn('BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT="$GW_JWT"', init)  # JWT -> gateway daemons
 
 
 class TestSshGatewayTransport(unittest.TestCase):

tests/unit/test_gateway_init.py

@@ -64,7 +64,7 @@ class TestEnvForDaemon(unittest.TestCase):
         self.assertNotIn("X", self._BASE)
 
 
-class TestControlPlaneEnvScoping(unittest.TestCase):
+class TestOrchestratorEnvScoping(unittest.TestCase):
     """The control-plane signing key stays with the orchestrator; the pre-minted
     `gateway` JWT goes to the data-plane daemons (issue #469 review). Scoping
     them per-process keeps a compromised data-plane daemon from reading the key
@@ -72,20 +72,20 @@ class TestControlPlaneEnvScoping(unittest.TestCase):
 
     _BASE = {
         "PATH": "/usr/bin",
-        "BOT_BOTTLE_CONTROL_PLANE_TOKEN": "sk-x",
-        "BOT_BOTTLE_CONTROL_AUTH_JWT": "gw-jwt",
+        "BOT_BOTTLE_ORCHESTRATOR_TOKEN": "sk-x",
+        "BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT": "gw-jwt",
     }
 
     def test_orchestrator_gets_key_not_jwt(self):
         env = _env_for_daemon("orchestrator", self._BASE)
-        self.assertEqual("sk-x", env["BOT_BOTTLE_CONTROL_PLANE_TOKEN"])
-        self.assertNotIn("BOT_BOTTLE_CONTROL_AUTH_JWT", env)
+        self.assertEqual("sk-x", env["BOT_BOTTLE_ORCHESTRATOR_TOKEN"])
+        self.assertNotIn("BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT", env)
 
     def test_data_plane_daemons_get_jwt_not_key(self):
         for name in ("egress", "git-gate", "git-http", "supervise"):
             env = _env_for_daemon(name, self._BASE)
-            self.assertNotIn("BOT_BOTTLE_CONTROL_PLANE_TOKEN", env, name)
-            self.assertEqual("gw-jwt", env["BOT_BOTTLE_CONTROL_AUTH_JWT"], name)
+            self.assertNotIn("BOT_BOTTLE_ORCHESTRATOR_TOKEN", env, name)
+            self.assertEqual("gw-jwt", env["BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT"], name)
 
 
 class TestSelectedDaemons(unittest.TestCase):

tests/unit/test_macos_consolidated_launch.py

@@ -58,7 +58,7 @@ class TestEnsureGateway(unittest.TestCase):
         from bot_bottle.backend.macos_container.infra import InfraEndpoint
         service = MagicMock()
         service.ensure_running.return_value = InfraEndpoint(
-            control_plane_url="http://192.168.128.2:8099",
+            orchestrator_url="http://192.168.128.2:8099",
             gateway_ip="192.168.128.2",
         )
         service.network = "bot-bottle-mac-gateway"
@@ -72,7 +72,7 @@ class TestEnsureGateway(unittest.TestCase):
         self.assertEqual("PEM", endpoint.gateway_ca_pem)
         self.assertEqual("bot-bottle-mac-gateway", endpoint.network)
 
-    def test_control_plane_and_gateway_share_one_address(self) -> None:
+    def test_orchestrator_and_gateway_share_one_address(self) -> None:
         """One infra container hosts both, so the gateway IP and the
         control-plane host are the same."""
         endpoint = self._run(self._service())

tests/unit/test_macos_infra.py

@@ -10,7 +10,7 @@ from bot_bottle.backend.macos_container.infra import (
     INFRA_DB_VOLUME,
     MacosInfraService,
     OrchestratorStartError,
-    probe_control_plane_url,
+    probe_orchestrator_url,
 )
 
 _INFRA = "bot_bottle.backend.macos_container.infra"
@@ -110,7 +110,7 @@ class TestInfraEnsureRunning(unittest.TestCase):
             mod.try_container_ipv4_on_network.return_value = "192.168.128.2"
             endpoint = svc.ensure_running()
         run.assert_not_called()
-        self.assertEqual("http://192.168.128.2:8099", endpoint.control_plane_url)
+        self.assertEqual("http://192.168.128.2:8099", endpoint.orchestrator_url)
         self.assertEqual("192.168.128.2", endpoint.gateway_ip)
 
     def test_changed_source_recreates(self) -> None:
@@ -176,16 +176,16 @@ class TestCaCertPem(unittest.TestCase):
                 svc.ca_cert_pem(timeout=0)
 
 
-class TestProbeControlPlane(unittest.TestCase):
+class TestProbeOrchestrator(unittest.TestCase):
     def test_returns_url_when_running(self) -> None:
         with patch(f"{_INFRA}.container_mod") as mod:
             mod.try_container_ipv4_on_network.return_value = "192.168.128.2"
-            self.assertEqual("http://192.168.128.2:8099", probe_control_plane_url())
+            self.assertEqual("http://192.168.128.2:8099", probe_orchestrator_url())
 
     def test_empty_when_absent(self) -> None:
         with patch(f"{_INFRA}.container_mod") as mod:
             mod.try_container_ipv4_on_network.return_value = ""
-            self.assertEqual("", probe_control_plane_url())
+            self.assertEqual("", probe_orchestrator_url())
 
 
 if __name__ == "__main__":

tests/unit/test_orchestrator_auth.py

@@ -6,7 +6,7 @@ import base64
 import json
 import unittest
 
-from bot_bottle.control_auth import ROLE_CLI, ROLE_GATEWAY, ROLES, mint, verify
+from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY, ROLES, mint, verify
 
 _KEY = "test-key"
 
@@ -45,14 +45,14 @@ class TestMintVerify(unittest.TestCase):
     def test_validly_signed_but_wrong_alg_rejected(self) -> None:
         # Alg-confusion: even a *correctly signed* token whose header claims a
         # non-HS256 alg must be rejected.
-        from bot_bottle.control_auth import _sign  # noqa: PLC0415
+        from bot_bottle.orchestrator_auth import _sign  # noqa: PLC0415
         signing_input = f"{_b64({'alg': 'none', 'typ': 'JWT'})}.{_b64({'role': 'cli'})}"
         self.assertIsNone(verify(f"{signing_input}.{_sign(_KEY, signing_input)}", _KEY))
 
     def test_validly_signed_but_undecodable_rejected(self) -> None:
         # A correct signature over a header that isn't valid base64/JSON still
         # fails closed rather than raising.
-        from bot_bottle.control_auth import _sign  # noqa: PLC0415
+        from bot_bottle.orchestrator_auth import _sign  # noqa: PLC0415
         signing_input = f"!!!not-base64!!!.{_b64({'role': 'cli'})}"
         self.assertIsNone(verify(f"{signing_input}.{_sign(_KEY, signing_input)}", _KEY))
 
@@ -67,7 +67,7 @@ class TestMintVerify(unittest.TestCase):
         header, _p, _s = mint(ROLE_CLI, _KEY).split(".")
         # Re-sign a token carrying an unknown role — a valid signature but a
         # role the control plane doesn't recognise must still be rejected.
-        from bot_bottle.control_auth import _sign  # noqa: PLC0415
+        from bot_bottle.orchestrator_auth import _sign  # noqa: PLC0415
         payload = _b64({"role": "root"})
         signing_input = f"{header}.{payload}"
         forged = f"{signing_input}.{_sign(_KEY, signing_input)}"

tests/unit/test_orchestrator_client.py

@@ -7,7 +7,7 @@ import unittest
 import urllib.error
 from unittest.mock import MagicMock, patch
 
-from bot_bottle.control_auth import ROLE_CLI, verify
+from bot_bottle.orchestrator_auth import ROLE_CLI, verify
 from bot_bottle.orchestrator.client import (
     OrchestratorClient,
     OrchestratorClientError,
@@ -20,13 +20,13 @@ _URLOPEN = "bot_bottle.orchestrator.client.urllib.request.urlopen"
 
 class TestHostAuthToken(unittest.TestCase):
     def test_mints_a_cli_token_from_the_host_key(self) -> None:
-        with patch("bot_bottle.orchestrator.client.host_control_plane_token",
+        with patch("bot_bottle.orchestrator.client.host_orchestrator_token",
                    return_value="signing-key"):
             tok = _host_auth_token()
         self.assertEqual(ROLE_CLI, verify(tok, "signing-key"))
 
     def test_returns_empty_when_key_unreadable(self) -> None:
-        with patch("bot_bottle.orchestrator.client.host_control_plane_token",
+        with patch("bot_bottle.orchestrator.client.host_orchestrator_token",
                    side_effect=OSError("no host root")):
             self.assertEqual("", _host_auth_token())
 

tests/unit/test_orchestrator_server.py

@@ -19,7 +19,7 @@ from contextlib import closing
 from pathlib import Path
 from unittest.mock import patch
 
-from bot_bottle.control_auth import ROLE_CLI, ROLE_GATEWAY, mint
+from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY, mint
 from bot_bottle.orchestrator.broker import StubBroker
 from bot_bottle.orchestrator.server import dispatch, make_server
 from bot_bottle.orchestrator.registry import BottleRecord, RegistryStore
@@ -284,7 +284,7 @@ class TestServerRoundTrip(unittest.TestCase):
         self.assertEqual(reg["bottle_id"], attr["bottle_id"])
 
 
-class TestControlPlaneAuth(unittest.TestCase):
+class TestOrchestratorAuth(unittest.TestCase):
     """Role-scoped control-plane tokens (issue #400 / #469 review): every route
     but /health needs a valid token, and the token's role gates which routes it
     reaches — a `gateway` data-plane token can't drive the operator routes."""
@@ -349,7 +349,7 @@ class TestControlPlaneAuth(unittest.TestCase):
         self.assertIsNotNone(self.orch.registry.get(rec.bottle_id))
 
     def _server_with_key(self, signing_key: str):
-        with patch.dict("os.environ", {"BOT_BOTTLE_CONTROL_PLANE_TOKEN": signing_key}):
+        with patch.dict("os.environ", {"BOT_BOTTLE_ORCHESTRATOR_TOKEN": signing_key}):
             server = make_server(self.orch, "127.0.0.1", 0)
         self.addCleanup(server.server_close)
         threading.Thread(target=server.serve_forever, daemon=True).start()
@@ -360,7 +360,7 @@ class TestControlPlaneAuth(unittest.TestCase):
     def _status(self, url: str, *, header: str | None = None) -> int:
         req = urllib.request.Request(url)
         if header is not None:
-            req.add_header("x-bot-bottle-control-auth", header)
+            req.add_header("x-bot-bottle-orchestrator-auth", header)
         try:
             return urllib.request.urlopen(req, timeout=5).status
         except urllib.error.HTTPError as e:
@@ -384,7 +384,7 @@ class TestControlPlaneAuth(unittest.TestCase):
         grants full cli access, so existing round-trip behavior is unchanged."""
         with patch.dict("os.environ", {}, clear=False):
             import os
-            os.environ.pop("BOT_BOTTLE_CONTROL_PLANE_TOKEN", None)
+            os.environ.pop("BOT_BOTTLE_ORCHESTRATOR_TOKEN", None)
             server = make_server(self.orch, "127.0.0.1", 0)
         self.addCleanup(server.server_close)
         self.assertEqual(ROLE_CLI, server.role_for(""))

tests/unit/test_policy_resolver.py

@@ -8,11 +8,11 @@ import urllib.error
 from unittest.mock import MagicMock, patch
 
 from bot_bottle.gateway.policy_resolver import (
-    CONTROL_AUTH_HEADER,
-    CONTROL_AUTH_JWT_ENV,
+    ORCHESTRATOR_AUTH_HEADER,
+    ORCHESTRATOR_AUTH_JWT_ENV,
     PolicyResolveError,
     PolicyResolver,
-    _control_auth_headers,
+    _orchestrator_auth_headers,
 )
 
 _URLOPEN = "bot_bottle.gateway.policy_resolver.urllib.request.urlopen"
@@ -29,16 +29,16 @@ def _http_error(code: int) -> urllib.error.HTTPError:
     return urllib.error.HTTPError("http://x/resolve", code, "err", {}, None)  # type: ignore[arg-type]
 
 
-class TestControlAuthHeaders(unittest.TestCase):
+class TestOrchestratorAuthHeaders(unittest.TestCase):
     def test_sends_the_gateway_jwt_when_configured(self) -> None:
-        with patch.dict("os.environ", {CONTROL_AUTH_JWT_ENV: "gateway.jwt.tok"}):
-            self.assertEqual({CONTROL_AUTH_HEADER: "gateway.jwt.tok"}, _control_auth_headers())
+        with patch.dict("os.environ", {ORCHESTRATOR_AUTH_JWT_ENV: "gateway.jwt.tok"}):
+            self.assertEqual({ORCHESTRATOR_AUTH_HEADER: "gateway.jwt.tok"}, _orchestrator_auth_headers())
 
     def test_sends_nothing_when_unset(self) -> None:
         import os
         with patch.dict("os.environ", {}, clear=False):
-            os.environ.pop(CONTROL_AUTH_JWT_ENV, None)
-            self.assertEqual({}, _control_auth_headers())
+            os.environ.pop(ORCHESTRATOR_AUTH_JWT_ENV, None)
+            self.assertEqual({}, _orchestrator_auth_headers())
 
 
 class TestPolicyResolver(unittest.TestCase):