docs: record the /mcp identity fixes

CAUCUS_PROJECT no longer influences the /mcp default; scope the README
table row to the bridge and the native connector, which run one process
per agent, and tell readers to name their agents explicitly when several
share the hub.

Author: obeone

CHANGELOG.md

@@ -22,6 +22,37 @@ and rename that heading to the version when you cut the release.
   now `mcp[cli]>=1.9,<2`, and a test asserts the ceiling stays in the published
   metadata. Lifting it means porting both modules to the 2.x server API first.
 
+- **Two `/mcp` clients could merge into one identity.** The default `join` name
+  was resolved once per *hub* process (from `CAUCUS_PROJECT`, else `mcp-client`),
+  but one hub process serves every Streamable HTTP client, so every client that
+  joined without an explicit `project` asked for that same name. A peer's liveness
+  at the hub is its in-flight `/receive` long-poll, so between two polls the
+  incumbent looked dead: `HubState.register` returned REPLACED rather than
+  CONTESTED and handed the newcomer the *existing* `Client` record: same token,
+  same inbox. Two agents, one identity, and no error raised anywhere.
+
+  The default name is now per session, taken from the MCP handshake's
+  `clientInfo.name` (sanitized, falling back to `mcp-client`), and `join` refuses
+  a name already held by another live session in the process with `name_in_use`.
+  Note that `clientInfo.name` identifies the MCP *host*, not the agent: two
+  sessions of the same host still collide, now explicitly. Pass
+  `join(project=...)` whenever several agents share the hub.
+
+  `CAUCUS_PROJECT` no longer influences the `/mcp` default. It keeps naming the
+  bridge and the native connector, which run one process per agent.
+
+### Security
+
+- **Reserved names were registrable over `/mcp`.** `join` bypasses `POST /register`
+  to skip the per-host anti-flood bucket (it is the wrong brake for a trusted
+  in-process caller), and in doing so it also skipped the `RegisterRequest`
+  pydantic model that rejects the control-plane identities. An MCP client could
+  `join(project="human")`, or `"hub"` / `"system"`, and fabricate operator
+  authority in the `sender` field other agents read; the REST path answers 422 for
+  exactly that reason. The two guards that model applied, the reserved-name
+  rejection and the 1-64 character bound, are now re-applied on the `/mcp` path,
+  returning `reserved_name` and `invalid_name`.
+
 ## [2.3.0](https://github.com/obeone/caucus-mcp/compare/v2.2.0...v2.3.0) (2026-07-25)
 
 ### Added

README.md

@@ -307,7 +307,7 @@ options, the security notes, and the manual route.
 | Variable | Default | Meaning |
 | --- | --- | --- |
 | `CAUCUS_HUB_URL` | `http://127.0.0.1:8765` | Hub the bridge and the native connector reach out to. Unused when the client speaks Streamable HTTP to `/mcp`, where the URL is the config. |
-| `CAUCUS_PROJECT` | working-dir basename | Name this agent registers under. Set it only when you want a name different from the directory, or when two checkouts share a basename. |
+| `CAUCUS_PROJECT` | working-dir basename | Name this agent registers under, for the bridge and the native connector (one process per agent). Set it only when you want a name different from the directory, or when two checkouts share a basename. Ignored over `/mcp`, where one hub process serves every client: there the name comes from the MCP handshake, or from `join(project=...)`. |
 | `CAUCUS_MCP_HTTP` | on for loopback | The Streamable HTTP MCP endpoint at `/mcp` is served by default on a loopback bind. Set to `0` to disable it, or to `1` to force it on a non-loopback bind (same as `--no-mcp-http` / `--mcp-http`). See [Connect over Streamable HTTP](#connect-over-streamable-http-no-bridge-subprocess). |
 
 Hub flags: `caucus-hub --host <ip> --port <n>` (defaults `127.0.0.1:8765`). The
@@ -470,6 +470,12 @@ the hub, with a DNS-rebinding guard on the handshake.
 The session is keyed on the `Mcp-Session-Id` header, so many agents share the one
 hub process; a background sweep drops sessions that armed but never joined.
 
+**Name your agents.** `join()` with no argument falls back to the name the MCP
+client announced at the handshake, which is the *host* ("claude-code", "codex"),
+not the agent. Two sessions of the same host therefore ask for the same name, and
+the second is refused with `name_in_use`. Pass `join(project="reviewer")`
+whenever more than one agent shares the hub.
+
 ### Which transport?
 
 Both paths expose the **same tools, with the same schemas and the same