fix(proxy): stop the --uds banner advertising a recipe that cannot work

Both startup banners printed an ANTHROPIC_UNIX_SOCKET=... claude line on a
socket bind. That configuration is the one this branch's own docs document as
broken: it satisfies Claude Code's api.anthropic.com host check but
reclassifies the session as API-key auth, so the session then fails to
authenticate. Runtime output was contradicting the docs and walking users into
the failure. Review feedback on #3151.

The socket branch of both banners now comes from uds.socket_usage_lines(), a
single agent-neutral block: the socket path, the transport requirement (the
client must speak HTTP over a Unix socket natively), a curl example, and a
link to the docs page that carries the per-client detail. The legacy banner's
hardcoded "Claude Code:" label is now computed alongside it, so the socket
bind no longer addresses one agent by name; both branches still render to the
same 70-column inner width.

Per-client wiring stays in the docs, where it can be qualified. Three tests
pin the contract: the unsupported recipe is absent, the replacement states the
requirement and links the docs, and no agent is named at all. They are pure
string assertions, so they run on every platform rather than only where
AF_UNIX exists.

Author: Ayushraj06-bit

headroom/cli/proxy.py

@@ -1636,16 +1636,13 @@ def proxy(
     else:
         tuning_section = ""
 
-    # A socket has no URL, and the client-side wiring for it is a different pair
-    # of env vars, so the banner's URL and Usage blocks both switch shape.
+    # A socket has no URL, and no per-agent recipe belongs here — see
+    # uds.socket_usage_lines() for why the banner stays transport-neutral.
     if config.uds:
+        from headroom.proxy.uds import socket_usage_lines
+
         listen_display = f"unix:{config.uds}"
-        usage_section = "\n".join(
-            (
-                f"  Claude Code:   ANTHROPIC_UNIX_SOCKET={config.uds} \\",
-                "                 ANTHROPIC_BASE_URL=http://api.anthropic.com claude",
-            )
-        )
+        usage_section = "\n".join(socket_usage_lines(config.uds))
     else:
         listen_display = f"http://{config.host}:{config.port}"
         usage_section = "\n".join(

headroom/proxy/server.py

@@ -5386,10 +5386,13 @@ def run_server(
     api_targets = resolve_api_targets(config.provider_api_overrides)
 
     if config.uds:
+        # No per-agent recipe on a socket bind; see uds.socket_usage_lines().
         listen_display = f"unix:{config.uds}"
-        usage_display = f"ANTHROPIC_UNIX_SOCKET={config.uds} claude"
+        usage_label = "Client:     "
+        usage_display = "must support HTTP over a Unix socket natively"
     else:
         listen_display = f"http://{config.host}:{config.port}"
+        usage_label = "Claude Code:"
         usage_display = f"ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude"
 
     if print_banner:
@@ -5420,7 +5423,7 @@ def run_server(
 ║    Conn Pool:       {pool_info:<52}║
 ╠══════════════════════════════════════════════════════════════════════╣
 ║  USAGE:                                                              ║
-║    Claude Code:   {usage_display:<51}║
+║    {usage_label}   {usage_display:<51}║
 ║    Cursor:        Set base URL in settings                           ║
 ╠══════════════════════════════════════════════════════════════════════╣
 ║  ENDPOINTS:                                                          ║

headroom/proxy/uds.py

@@ -36,6 +36,7 @@
 __all__ = [
     "UDS_SUPPORTED",
     "UdsError",
+    "socket_usage_lines",
     "max_uds_path_length",
     "prepare_uds_path",
     "remove_uds_path",
@@ -105,6 +106,30 @@ def _is_live_socket(path: Path) -> bool:
         sock.close()
 
 
+# Docs page carrying the client-compatibility detail the banner has no room for.
+UDS_DOCS_URL = "https://headroom-docs.vercel.app/docs/proxy#serving-on-a-unix-socket"
+
+
+def socket_usage_lines(path: str | os.PathLike[str]) -> tuple[str, ...]:
+    """How the startup banner describes a socket bind, for every banner.
+
+    Deliberately names no agent and hands out no environment variables. An
+    earlier revision printed an ``ANTHROPIC_UNIX_SOCKET=... claude`` recipe here,
+    which is a configuration that does not work: it satisfies Claude Code's
+    ``api.anthropic.com`` host check but reclassifies the session as API-key
+    auth, and the session then fails to authenticate. Printing it at startup
+    turned a known-negative result into first-party guidance. The rule this
+    encodes is that the banner states a transport requirement and points at the
+    docs; per-client wiring belongs in the docs, where it can be qualified.
+    """
+    return (
+        f"  Socket:        {path}",
+        "  Client:        must support HTTP over a Unix socket natively",
+        f"  Example:       curl --unix-socket {path} http://localhost/health",
+        f"  Details:       {UDS_DOCS_URL}",
+    )
+
+
 def _missing_ancestors(target: Path) -> list[Path]:
     """Directories along *target* that do not exist yet, shallowest first."""
     missing: list[Path] = []

tests/test_proxy_uds.py

@@ -25,6 +25,7 @@
     prepare_uds_path,
     remove_uds_path,
     require_uds_support,
+    socket_usage_lines,
 )
 
 requires_uds = pytest.mark.skipif(
@@ -130,6 +131,46 @@ def test_unreadable_existing_parent_defers_to_bind(tmp_path: Path) -> None:
         _require_safe_existing_parent(tmp_path)
 
 
+# --------------------------------------------------------------------------
+# Startup banner — a socket bind must not advertise a broken recipe.
+# --------------------------------------------------------------------------
+
+
+def test_socket_usage_lines_omit_the_unsupported_claude_code_recipe() -> None:
+    """Regression: the banner once printed a configuration that cannot work.
+
+    `ANTHROPIC_UNIX_SOCKET=... claude` passes Claude Code's api.anthropic.com
+    host check but reclassifies the session as API-key auth, and the session
+    then fails to authenticate. Printing it at startup turned a known-negative
+    field result into first-party runtime guidance.
+    """
+    rendered = "\n".join(socket_usage_lines("/run/headroom/proxy.sock"))
+
+    assert "ANTHROPIC_UNIX_SOCKET" not in rendered
+    assert "ANTHROPIC_BASE_URL" not in rendered
+    assert "claude" not in rendered.lower()
+
+
+def test_socket_usage_lines_state_the_transport_requirement() -> None:
+    """What replaces the recipe has to be useful, not merely absent."""
+    path = "/run/headroom/proxy.sock"
+
+    rendered = "\n".join(socket_usage_lines(path))
+
+    assert path in rendered
+    assert "HTTP over a Unix socket" in rendered
+    assert "curl --unix-socket" in rendered
+    assert "serving-on-a-unix-socket" in rendered
+
+
+def test_socket_usage_lines_name_no_agent() -> None:
+    """Transport-neutral: the banner singles out no client."""
+    rendered = "\n".join(socket_usage_lines("/run/headroom/proxy.sock")).lower()
+
+    for agent in ("claude", "codex", "opencode", "cursor", "aider", "copilot"):
+        assert agent not in rendered, f"banner should not name {agent}"
+
+
 # --------------------------------------------------------------------------
 # Path preparation — needs a real AF_UNIX platform.
 # --------------------------------------------------------------------------