superqode 2.2.2__tar.gz → 2.2.4__tar.gz

{superqode-2.2.2 → superqode-2.2.4}/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.4] - 2026-09-13
+
+Hosting a UHP harness gets its own install extra, so `serve uhp` no longer
+asks for the A2A stack. `scripts/run_uhp_conformance.sh` runs the HarnessRouter
+conformance suite against a local bind.
+
+### 🧩 Unified Harness Protocol
+
+- New `superqode[uhp]` extra: FastAPI and uvicorn, the two packages
+  `serve uhp` needs. Hosting a UHP harness no longer means installing
+  `superqode[a2a]` and its unrelated A2A stack. The client needs neither,
+  because httpx and httpx-sse are core dependencies.
+- `serve uhp` without those packages now names the extra to install. It exited
+  with a raw `ModuleNotFoundError` traceback.
+- `Dockerfile.uhp` installs `.[uhp]` instead of `.[a2a]`.
+- `scripts/run_uhp_conformance.sh` stands up a local bind and runs the
+  HarnessRouter conformance suite against it, in a scratch directory. The
+  suite is a stock UHP client and does not send `X-Provider-Api-Key`, so a
+  BYOK bind cannot be measured directly.
+
+## [2.2.3] - 2026-09-13
+
+Security fixes for the UHP client and the BYOK server bind shipped in 2.2.2.
+Anyone who ran `superqode connect uhp` on 2.2.2 sent their model key to the
+address they connected to, including on the anonymous discovery request, so
+upgrading is worth doing before the next connect. No API changed and no
+protocol behaviour changed: the Core conformance result is the same 38/40.
+
+### 🔐 UHP security
+
+- The client sends `X-Provider-Api-Key` on a task submission only. It was
+  attached to every request, including the anonymous discovery and catalog
+  GETs, so `connect uhp --base-url <address>` handed that address the caller's
+  model key before the caller had decided to trust it. The key is also
+  withheld from a remote plaintext `http://` origin, with a warning.
+- A caller's model key no longer races with another caller's. It is written to
+  every environment variable the provider reads, and BYOK turns are serialised
+  for as long as it is in the process environment, which LiteLLM reads
+  credentials from. Concurrent turns previously overwrote each other's key.
+- `Dockerfile.uhp` no longer passes `--api-key` on the command line. The bearer
+  came from the environment either way, and the argument published it in
+  `/proc/1/cmdline`, which the bound harness's shell tool can read.
+- On a remote bind each session gets its own directory under the working
+  directory, so callers cannot read each other's files or session transcripts.
+  A local bind still runs in the directory it was given.
+- Request metadata can no longer set harness runtime controls such as
+  `agent_max_iterations`. Caller context is still passed through.
+- Bearer comparison is constant time.
+
 ## [2.2.2] - 2026-09-12
 
 The installed CLI can complete a harness turn against a BYOK UHP host such as

{superqode-2.2.2 → superqode-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.2
+Version: 2.2.4
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -66,6 +66,9 @@ Provides-Extra: a2a
 Requires-Dist: a2a-sdk[fastapi,sqlite]<2.0.0,>=1.1.2; extra == "a2a"
 Requires-Dist: fastapi>=0.115.0; extra == "a2a"
 Requires-Dist: uvicorn>=0.32.0; extra == "a2a"
+Provides-Extra: uhp
+Requires-Dist: fastapi>=0.115.0; extra == "uhp"
+Requires-Dist: uvicorn>=0.32.0; extra == "uhp"
 Provides-Extra: adk
 Requires-Dist: google-adk<3.0,>=2.1.0; extra == "adk"
 Provides-Extra: openai-agents

{superqode-2.2.2 → superqode-2.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.2.2"
+version = "2.2.4"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"
@@ -113,6 +113,13 @@ a2a = [
     "fastapi>=0.115.0",
     "uvicorn>=0.32.0",
 ]
+uhp = [
+    # `serve uhp` only. The UHP client needs nothing extra: httpx and
+    # httpx-sse are core. Deliberately no a2a-sdk, so hosting a UHP harness
+    # does not drag in an unrelated protocol stack.
+    "fastapi>=0.115.0",
+    "uvicorn>=0.32.0",
+]
 adk = [
     "google-adk>=2.1.0,<3.0",
 ]

{superqode-2.2.2 → superqode-2.2.4}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.2.2"
+__version__ = "2.2.4"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

{superqode-2.2.2 → superqode-2.2.4}/src/superqode/commands/serve.py

@@ -375,7 +375,7 @@ def serve_uhp(
     This is SuperQode's own harness speaking UHP — complementary to
     HarnessRouter, not a multi-backend runner replacement.
     """
-    from superqode.harness.uhp_server import create_uhp_server
+    from superqode.harness.uhp_server import MissingUHPServerDependency, create_uhp_server
 
     is_loopback = host in {"127.0.0.1", "localhost", "::1"}
     if not is_loopback and not allow_remote:
@@ -387,16 +387,19 @@ def serve_uhp(
             "the caller's X-Provider-Api-Key."
         )
 
-    server = create_uhp_server(
-        spec=spec_path,
-        provider=provider,
-        model=model_name,
-        working_directory=working_dir.resolve(),
-        api_key=api_key,
-        harness_id=harness_id,
-        public_catalog=allow_remote,
-        require_caller_provider_key=allow_remote,
-    )
+    try:
+        server = create_uhp_server(
+            spec=spec_path,
+            provider=provider,
+            model=model_name,
+            working_directory=working_dir.resolve(),
+            api_key=api_key,
+            harness_id=harness_id,
+            public_catalog=allow_remote,
+            require_caller_provider_key=allow_remote,
+        )
+    except MissingUHPServerDependency as exc:
+        raise click.ClickException(str(exc)) from exc
     console.print(
         f"[cyan]Serving SuperQode UHP {server.discovery_document()['default_version']} "
         f"on http://{host}:{port}[/cyan]"

{superqode-2.2.2 → superqode-2.2.4}/src/superqode/harness/uhp_client.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import base64
 import json
+import logging
 import mimetypes
 import os
 import uuid
@@ -20,9 +21,12 @@ from collections.abc import AsyncIterator, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 
 import httpx
 
+logger = logging.getLogger(__name__)
+
 UHP_PROTOCOL_VERSION = "2026-08-11"
 
 #: Sent on every request so a server does not silently answer at another
@@ -34,8 +38,12 @@ VERSION_HEADER = "UHP-Version"
 IDEMPOTENCY_HEADER = "Idempotency-Key"
 
 #: Caller model key for a BYOK UHP server. SuperQode does not send its own.
+#: A SuperQode extension, not part of UHP. Task submission only.
 PROVIDER_KEY_HEADER = "X-Provider-Api-Key"
 
+#: Plaintext http is safe enough to carry a key to these.
+_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+
 
 def _caller_provider_api_key() -> str:
     """Return the caller's model key for a BYOK UHP server, if present."""
@@ -494,7 +502,8 @@ class UHPClient:
             timeout, because a harness can work for minutes between events.
         headers: Extra headers merged into every request.  A cookie header
             belongs here for a server that gates the API with a console
-            session instead of a bearer token.
+            session instead of a bearer token.  ``PROVIDER_KEY_HEADER`` is the
+            exception: it rides task submission only.
         client: An existing ``httpx.AsyncClient`` to borrow instead of creating
             one.  A borrowed client is never closed by ``aclose``.
     """
@@ -511,19 +520,46 @@ class UHPClient:
         self.base_url = self._normalize_base_url(base_url)
         self.api_key = api_key
         self.timeout = timeout
-        self._headers = {
+        merged = {
             "Accept": "application/json",
             VERSION_HEADER: UHP_PROTOCOL_VERSION,
             **dict(headers or {}),
         }
+        # Held aside, not merged: a model key rides task submission only.
+        self._provider_key = str(merged.pop(PROVIDER_KEY_HEADER, "") or "").strip()
+        self._headers = merged
         if api_key:
             self._headers["Authorization"] = f"Bearer {api_key}"
-        provider_key = _caller_provider_api_key()
-        if provider_key and PROVIDER_KEY_HEADER not in self._headers:
-            self._headers[PROVIDER_KEY_HEADER] = provider_key
         self._client = client
         self._owns_client = client is None
 
+    def _origin_is_confidential(self) -> bool:
+        """Whether this base URL protects a credential in transit."""
+        parsed = urlparse(self.base_url)
+        if parsed.scheme == "https":
+            return True
+        return (parsed.hostname or "").lower() in _LOOPBACK_HOSTS
+
+    def _provider_key_headers(self) -> dict[str, str]:
+        """The caller's model key, for a task submission only.
+
+        Withheld from a plaintext origin, not refused there: a server reached
+        over http may not want the key at all, and one that does answers
+        ``missing_provider_key``.
+        """
+        key = self._provider_key or _caller_provider_api_key()
+        if not key:
+            return {}
+        if not self._origin_is_confidential():
+            logger.warning(
+                "Not sending %s to %s: the connection is plaintext http, which would put the "
+                "model key on the wire in clear. Use an https base URL if this server needs it.",
+                PROVIDER_KEY_HEADER,
+                self.base_url,
+            )
+            return {}
+        return {PROVIDER_KEY_HEADER: key}
+
     @staticmethod
     def _normalize_base_url(base_url: str) -> str:
         """Return the server root without a trailing slash or ``/v1`` suffix."""
@@ -816,7 +852,10 @@ class UHPClient:
             message, input_files=input_files, inline_files=inline_files
         )
         body = self.build_response_body(prepared, stream=False, **kwargs)
-        headers = {IDEMPOTENCY_HEADER: idempotency_key or self.new_idempotency_key()}
+        headers = {
+            IDEMPOTENCY_HEADER: idempotency_key or self.new_idempotency_key(),
+            **self._provider_key_headers(),
+        }
         payload = await self._request("POST", "responses", json_body=body, headers=headers)
         if not isinstance(payload, Mapping):
             raise UHPServerError("UHP server returned no response object")
@@ -850,6 +889,7 @@ class UHPClient:
             **self._headers,
             "Accept": "text/event-stream",
             IDEMPOTENCY_HEADER: idempotency_key or self.new_idempotency_key(),
+            **self._provider_key_headers(),
         }
         pending_error: UHPError | None = None
         try:

{superqode-2.2.2 → superqode-2.2.4}/src/superqode/harness/uhp_server.py

@@ -13,12 +13,14 @@ session listing) are deferred.
 from __future__ import annotations
 
 import asyncio
+import hmac
 import json
 import os
 import re
 import time
 import uuid
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
+from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -42,9 +44,27 @@ DISCOVERY_OBJECT = "uhp.discovery"
 
 IDEMPOTENCY_HEADER = "Idempotency-Key"
 
+#: Runtime controls, not caller context. A request body may not set these.
+RESERVED_METADATA_KEYS = frozenset(
+    {
+        "agent_max_iterations",
+        "delegation_depth",
+        "harness_digest",
+        "harness_source",
+        "provider_api_key",
+    }
+)
+
+#: Guards the caller key in os.environ, which the whole process shares.
+_PROVIDER_ENV_LOCK = asyncio.Lock()
+
 HarnessRunner = Callable[["UHPRunRequest"], Awaitable["UHPRunResult"]]
 
 
+class MissingUHPServerDependency(RuntimeError):
+    """Serving UHP needs the `uhp` extra; the client does not."""
+
+
 @dataclass(frozen=True)
 class UHPRunRequest:
     """Inputs handed to the bound harness runner."""
@@ -167,6 +187,9 @@ class UHPServerConfig:
     public_catalog: bool = False
     #: Refuse a harness turn unless the caller sent PROVIDER_KEY_HEADER.
     require_caller_provider_key: bool = False
+    #: Per-session directory under working_directory, so callers on a shared
+    #: bind cannot read each other's files. Off locally: work in the project.
+    isolate_session_workspaces: bool = False
 
 
 def _package_version() -> str:
@@ -178,18 +201,58 @@ def _package_version() -> str:
         return "0.0.0"
 
 
-def _provider_key_env(provider: str) -> str:
-    """Env var LiteLLM reads for this provider (caller BYOK)."""
+def _provider_key_envs(provider: str) -> tuple[str, ...]:
+    """Every env var LiteLLM may read for this provider (caller BYOK).
+
+    All of them, not just the first: which one LiteLLM reads is its choice,
+    and Google alone has two.
+    """
     try:
         from superqode.providers.registry import PROVIDERS
 
         pdef = PROVIDERS.get(provider)
-        names = getattr(pdef, "env_vars", None) or ()
+        names = tuple(str(name) for name in (getattr(pdef, "env_vars", None) or ()) if name)
         if names:
-            return str(names[0])
+            return names
     except Exception:
         pass
-    return f"{(provider or 'OPENAI').upper()}_API_KEY"
+    return (f"{(provider or 'OPENAI').upper()}_API_KEY",)
+
+
+@asynccontextmanager
+async def _caller_provider_key(token: str, env_names: Sequence[str]) -> AsyncIterator[None]:
+    """Hold one caller's model key in ``os.environ`` for the length of a turn.
+
+    Serialises BYOK turns: the environment is process-global, so overlapping
+    turns would otherwise send each other's key.
+    """
+    if not token:
+        yield
+        return
+    async with _PROVIDER_ENV_LOCK:
+        previous = {name: os.environ.get(name) for name in env_names}
+        for name in env_names:
+            os.environ[name] = token
+        try:
+            yield
+        finally:
+            for name, value in previous.items():
+                if value is None:
+                    os.environ.pop(name, None)
+                else:
+                    os.environ[name] = value
+
+
+def _caller_metadata(body: Mapping[str, Any]) -> dict[str, Any]:
+    """Caller-supplied metadata with the runtime's own control keys removed."""
+    raw = body.get("metadata")
+    if not isinstance(raw, Mapping):
+        return {}
+    return {
+        str(key): value
+        for key, value in raw.items()
+        if str(key) not in RESERVED_METADATA_KEYS and not str(key).startswith("_")
+    }
 
 
 def harness_id_from_name(name: str) -> str:
@@ -372,8 +435,15 @@ class UHPServer:
     # -- FastAPI app ------------------------------------------------------------
 
     def _build_app(self) -> Any:
-        from fastapi import FastAPI
-        from fastapi.responses import JSONResponse, StreamingResponse
+        try:
+            from fastapi import FastAPI
+            from fastapi.responses import JSONResponse, StreamingResponse
+        except ModuleNotFoundError as exc:  # pragma: no cover - install-shape error
+            raise MissingUHPServerDependency(
+                "Serving UHP needs FastAPI and uvicorn, which are not installed.\n"
+                "  pip install 'superqode[uhp]'\n"
+                "The UHP client works without them."
+            ) from exc
 
         app = FastAPI(
             title="SuperQode UHP Server",
@@ -706,7 +776,8 @@ class UHPServer:
                 code="invalid_credential",
                 message="Authorization must be a Bearer token.",
             )
-        if token != expected:
+        # Bytes, because compare_digest rejects a non-ASCII str.
+        if not hmac.compare_digest(token.encode("utf-8"), expected.encode("utf-8")):
             return _error_envelope(
                 error_type="authentication_error",
                 code="invalid_credential",
@@ -714,6 +785,15 @@ class UHPServer:
             )
         return None
 
+    def _workspace_for(self, session_id: str) -> Path:
+        """The directory a turn runs in."""
+        root = Path(self.config.working_directory)
+        if not self.config.isolate_session_workspaces:
+            return root
+        workspace = root / "sessions" / session_id
+        workspace.mkdir(parents=True, exist_ok=True)
+        return workspace
+
     def _validate_harness_selection(
         self, body: Mapping[str, Any]
     ) -> tuple[int, dict[str, Any]] | None:
@@ -816,7 +896,7 @@ class UHPServer:
             prompt=prompt,
             model=model,
             provider=self.config.provider,
-            working_directory=Path(self.config.working_directory),
+            working_directory=self._workspace_for(session_id),
             session_id=session_id,
             response_id=response_id,
             previous_response_id=previous_response_id,
@@ -827,7 +907,7 @@ class UHPServer:
             cancel_event=self._cancel_events[response_id],
             metadata={
                 "harness_id": self.config.harness_id,
-                **(dict(body["metadata"]) if isinstance(body.get("metadata"), Mapping) else {}),
+                **_caller_metadata(body),
                 **({"provider_api_key": provider_api_key} if provider_api_key else {}),
             },
         )
@@ -1039,18 +1119,15 @@ class UHPServer:
             key: value for key, value in dict(request.metadata).items() if key != "provider_api_key"
         }
         token = str(request.metadata.get("provider_api_key") or "")
-        env_name = _provider_key_env(provider)
-        previous = os.environ.get(env_name)
-        if token:
-            os.environ[env_name] = token
         try:
-            result = await session.prompt(
-                prompt,
-                provider=provider,
-                model=model,
-                working_directory=request.working_directory,
-                metadata=run_metadata,
-            )
+            async with _caller_provider_key(token, _provider_key_envs(provider)):
+                result = await session.prompt(
+                    prompt,
+                    provider=provider,
+                    model=model,
+                    working_directory=request.working_directory,
+                    metadata=run_metadata,
+                )
         except Exception:
             return UHPRunResult(
                 status="failed",
@@ -1059,12 +1136,6 @@ class UHPServer:
                 error_code="harness_error",
                 usage=None,
             )
-        finally:
-            if token:
-                if previous is None:
-                    os.environ.pop(env_name, None)
-                else:
-                    os.environ[env_name] = previous
 
         if request.cancel_event and request.cancel_event.is_set():
             return UHPRunResult(
@@ -1087,8 +1158,12 @@ def create_uhp_server(
     runner: HarnessRunner | None = None,
     public_catalog: bool = False,
     require_caller_provider_key: bool = False,
+    isolate_session_workspaces: bool | None = None,
 ) -> UHPServer:
-    """Build a UHP server bound to one SuperQode HarnessSpec."""
+    """Build a UHP server bound to one SuperQode HarnessSpec.
+
+    ``isolate_session_workspaces`` defaults to whether the bind is BYOK.
+    """
     from superqode.harness import get_harness_template, load_harness_spec
 
     if spec is None:
@@ -1121,5 +1196,10 @@ def create_uhp_server(
         conformance_class="core",
         public_catalog=public_catalog,
         require_caller_provider_key=require_caller_provider_key,
+        isolate_session_workspaces=(
+            require_caller_provider_key
+            if isolate_session_workspaces is None
+            else isolate_session_workspaces
+        ),
     )
     return UHPServer(config, runner=runner, spec=loaded)

{superqode-2.2.2 → superqode-2.2.4}/src/superqode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.2
+Version: 2.2.4
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -66,6 +66,9 @@ Provides-Extra: a2a
 Requires-Dist: a2a-sdk[fastapi,sqlite]<2.0.0,>=1.1.2; extra == "a2a"
 Requires-Dist: fastapi>=0.115.0; extra == "a2a"
 Requires-Dist: uvicorn>=0.32.0; extra == "a2a"
+Provides-Extra: uhp
+Requires-Dist: fastapi>=0.115.0; extra == "uhp"
+Requires-Dist: uvicorn>=0.32.0; extra == "uhp"
 Provides-Extra: adk
 Requires-Dist: google-adk<3.0,>=2.1.0; extra == "adk"
 Provides-Extra: openai-agents

{superqode-2.2.2 → superqode-2.2.4}/src/superqode.egg-info/requires.txt

@@ -151,6 +151,10 @@ coverage>=7.0.0
 bandit>=1.8.0
 httpx>=0.28.1
 
+[uhp]
+fastapi>=0.115.0
+uvicorn>=0.32.0
+
 [ui-testing]
 selenium>=4.27.0
 playwright>=1.49.0

{superqode-2.2.2 → superqode-2.2.4}/tests/test_uhp_client.py

@@ -14,6 +14,7 @@ from superqode.harness import (
     UHPHarnessProtocolAdapter,
 )
 from superqode.harness.uhp_client import (
+    PROVIDER_KEY_HEADER,
     UHPAuthenticationError,
     UHPError,
     UHPHarnessError,
@@ -1250,3 +1251,105 @@ def test_build_user_input_supports_inline_data_url():
     assert part["type"] == "input_file"
     assert part["filename"] == "note.txt"
     assert part["file_data"].startswith("data:text/plain;base64,")
+
+
+# ── the caller's model key travels on task submission only ─────────────────────
+
+
+def _recording_client(seen, *, base_url=BASE_URL):
+    """A client that records the headers of every request it makes."""
+
+    def handler(request):
+        seen.append((request.url.path, dict(request.headers)))
+        if request.url.path.endswith("/uhp"):
+            return httpx.Response(200, json={"object": "uhp.discovery", "protocol": "uhp"})
+        if request.url.path.endswith("/harnesses"):
+            return httpx.Response(200, json={"harnesses": [{"id": "chrn_a"}]})
+        return httpx.Response(200, json=_response_payload())
+
+    transport = httpx.MockTransport(handler)
+    return UHPClient(
+        base_url,
+        api_key="key-123",
+        client=httpx.AsyncClient(transport=transport),
+    )
+
+
+@pytest.mark.anyio
+async def test_provider_key_is_withheld_from_discovery_and_catalog(monkeypatch):
+    """Discovery runs before the user has decided to trust the host."""
+    monkeypatch.setenv("SUPERQODE_PROVIDER", "google")
+    monkeypatch.setenv("GEMINI_API_KEY", "caller-gemini-key")
+    seen = []
+
+    async with _recording_client(seen) as client:
+        await client.discover()
+        await client.list_harnesses()
+
+    assert seen, "no requests were recorded"
+    for path, headers in seen:
+        assert PROVIDER_KEY_HEADER.lower() not in headers, f"{path} carried the provider key"
+
+
+@pytest.mark.anyio
+async def test_provider_key_is_sent_on_task_submission(monkeypatch):
+    monkeypatch.setenv("SUPERQODE_PROVIDER", "google")
+    monkeypatch.setenv("GEMINI_API_KEY", "caller-gemini-key")
+    seen = []
+
+    async with _recording_client(seen) as client:
+        await client.create_response("run this")
+
+    path, headers = seen[-1]
+    assert path.endswith("/responses")
+    assert headers[PROVIDER_KEY_HEADER.lower()] == "caller-gemini-key"
+
+
+@pytest.mark.anyio
+async def test_provider_key_from_headers_argument_is_also_held_back(monkeypatch):
+    """However the key arrived, it is a credential and not a transport header."""
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    monkeypatch.delenv("GOOGLE_API_KEY", raising=False)
+    seen = []
+
+    def handler(request):
+        seen.append((request.url.path, dict(request.headers)))
+        return httpx.Response(200, json={"object": "uhp.discovery", "protocol": "uhp"})
+
+    client = UHPClient(
+        BASE_URL,
+        headers={PROVIDER_KEY_HEADER: "explicit-key"},
+        client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+    )
+    async with client:
+        await client.discover()
+
+    assert PROVIDER_KEY_HEADER.lower() not in seen[0][1]
+
+
+@pytest.mark.anyio
+async def test_provider_key_is_withheld_over_plaintext_http(monkeypatch, caplog):
+    """Withheld, not fatal: an http server may not want the key at all."""
+    monkeypatch.setenv("SUPERQODE_PROVIDER", "google")
+    monkeypatch.setenv("GEMINI_API_KEY", "caller-gemini-key")
+    seen = []
+
+    with caplog.at_level("WARNING"):
+        async with _recording_client(seen, base_url="http://uhp.example.com") as client:
+            await client.create_response("run this")
+
+    assert PROVIDER_KEY_HEADER.lower() not in seen[-1][1]
+    assert "plaintext http" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_plaintext_loopback_still_carries_the_key(monkeypatch):
+    """HarnessRouter CE runs on loopback, where nothing leaves the machine."""
+    monkeypatch.setenv("SUPERQODE_PROVIDER", "google")
+    monkeypatch.setenv("GEMINI_API_KEY", "caller-gemini-key")
+    seen = []
+
+    async with _recording_client(seen, base_url="http://127.0.0.1:3000") as client:
+        await client.create_response("run this")
+
+    assert seen[-1][1][PROVIDER_KEY_HEADER.lower()] == "caller-gemini-key"