feat: friendly peer names, self-id, pretty channel content, quieter default port

[nnemirovsky]

Summary

Five focused fixes for v0.3.0:

1. Friendly peer names. channel.UniqueName() now mints <adjective>-<noun>-<3-char-base36> (e.g. wild-wasp-3kx) instead of cc-<host>-<pid>-<rand>. Two curated ~200-word lists live in internal/channel/wordlist.go; combined with the suffix the keyspace is ~1.86 billion. PEERBUS_NAME is honoured verbatim as an operator override.

2. Collision safety. Same-token collisions are essentially impossible given the keyspace. Different-token rejection (the only case the broker treats as a real conflict) is now surfaced as the typed adapter.ErrNameClaimed (mapped from the broker's StatusPolicyViolation + name claimed under a different token close reason). The cc adapter probe-registers before starting the resume loop and rotates the name on ErrNameClaimed up to 6 attempts. ResumingClient.connect short-circuits the redial backoff on a permanent rejection so a misconfig cannot spin forever. PEERBUS_NAME is never rotated.

3. Self-identification. Two-part fix, both required by the design:

   • On every successful register the cc adapter emits ONE notifications/claude/channel system push: content: "📡 connected as <self-name>", meta: {kind: "system", self: "<self-name>"}. Appears in turn 1 of the session. (Claude Code's UI already prefixes the notification with the MCP server name, rendered as peerbus: <content>, so the word "peerbus" is dropped from the body to avoid duplicated noise.)
   • bus.peers returns { self, peers } (self filtered out of the peers list). Plumbed through mcp.Bus.Peers and channel.OutboundBus.Peers (signature widened to (self, peers, err)). No separate bus.whoami tool — the structured result + startup push fully cover it.

4. Single-line channel content. Replaces the raw-JSON content body with a compact one-liner:

   📨 <kind> from <from>: "<decoded body>"
   

   <kind> is msg or broadcast. Single-line by design: Claude Code's renderer collapses embedded newlines into spaces and then truncates with an ellipsis, so the earlier multi-line From: / Type: / Content: block was wasted vertical space (observed live in a 2-session test). Claude Code's UI also prefixes the line with the MCP server name (rendered as peerbus: <content>), so the word "peerbus" is dropped from the body to avoid duplicated noise. Body-decoding rules in order: (i) JSON string -> unwrap; (ii) JSON object with text / message / content field -> use that; (iii) compact JSON fallback. kind is plumbed through channel.Inbound.Kind and also surfaced as a meta attribute on the notification.

5. Quieter default broker port. 127.0.0.1:8080 -> 127.0.0.1:47821. Verified clear of /etc/services on macOS, well below the OS ephemeral range, and not a 'tutorial-already-running' default like 8080. Updated: internal/broker/config.go, Dockerfile EXPOSE, deploy/compose.yml ports + PEERBUS_LISTEN, deploy/peerbus-broker.run, README.md, docs/integrations/generic-adapter.md, CLAUDE.md. Tests use ephemeral httptest ports — no test broke.

Also: scrubbed migration / v0.1.0 / peerbus-broker / peerbus-adapter chatter from README.md, source-file comments (cmd/peerbus/*.go), and docs/integrations/generic-adapter.md. Pre-1.0 — version history stays in docs/plans/completed/. Compose service key (peerbus-broker:) and deploy/peerbus-broker.run filename intentionally kept (role / service identifier, not version chatter).

Local-test recipe

git checkout friendly-names-v3-final
go install ./cmd/peerbus
# Restart the broker against the new default port (or your own PEERBUS_LISTEN).
# Re-register the cc adapter:
claude mcp remove peerbus  # if previously added
claude mcp add peerbus -- peerbus adapter --adapter=cc
# Open two Claude Code sessions wired to this MCP server; each should:
#   - print '📡 connected as <friendly-name>' on turn 1 (the UI itself prefixes it with 'peerbus:'),
#   - see {self, peers} from bus.peers,
#   - render incoming messages as '📨 msg from <from>: "<text>"' (or 'broadcast from ...').

Validation

go build ./...           OK
gofmt -l .               clean
gofumpt -l .             clean
go vet ./...             OK
go test ./...            170 passed
go test -race ./...      170 passed
go test -count=3 ./internal/channel    63 passed
golangci-lint run ./...  0 issues
make build               OK (bin/peerbus)
make deploy-validate     OK (compose config -q)

Do not merge — user wants to install + smoke-test via go install before merging.