feat: presence-derived parley_list_users (who's live on the bus)

[sharpTrick]

What & why

Adds parley_list_users — an MCP tool that reports who is live on the bus, with an optional glob filter (e.g. claude-*), for picking a hand-off target.

This started as "should list users be a core seam method every backend implements?" The answer was no: the seam is six methods on purpose, several backends have no enumerable user set (Redis/NATS/Discord/Telegram), and a mandatory listUsers would mean four different things wearing one name — the failure the conformance suite exists to prevent.

The better design (Patrick's insight): make presence a message. Each bridge announces hello / heartbeat / goodbye, and liveness is derived entirely above the seam from post/fetchRecent + a TTL window.

Result

• Works identically on every backend — no new seam method.
• Lists an idle instance that has never posted (the case a sender-scan misses).
• Zero changes to any backend plugin; the conformance suite is unchanged — the repo's own proof that prime directive chore: scaffold five new backend packages (postgres, zulip, discord, telegram, slack) #2 held.
• Presence streams are isolated: derived presence topics are never subscribed and never enter catch-up/dedup, so heartbeats never surface as <channel> events or pollute durable history.
• Reports Parley-participant liveness, not a human directory — a human in a native client appears once they send a real message.

Design decisions (locked with the user)

• Dedicated presence stream (not heartbeats in real topics) — keeps durable history and push clean, no Message-model change.
• Presence-only, uniform (not presence + per-backend directory) — keeps the "same behavior everywhere" property.

Changes (all in bridge-core)

• engine/presence.ts — presenceTopicFor, encode/decode, computeLive (TTL liveness)
• transport/presence-loop.ts — best-effort hello/heartbeat/goodbye emitter
• identity-filter.ts — matchGlob / filterHandles
• transport/tools.ts — parley_list_users tool (+ ToolDeps gains presenceTtlMs/now)
• lifecycle wiring: stdio-bridge (attach/shutdown) + http (app scope)
• config.ts — presence block (enabled/heartbeat_ms/ttl_ms)
• docs: DESIGN §7/§11, README; fixed the stale §4 "real account lookup for Matrix/XMPP" note (both echo the handle today)

Testing

• 154 tests pass, typecheck clean. 25 new unit tests (presence, glob, emitter loop, 6 tool cases).
• End-to-end on a real SQLite backend through the full bridge lifecycle — all 7 checks passed: idle agent discoverable via presence alone; filter narrows; real messages never pollute the presence stream or invent a user; clean-shutdown goodbye drops fast; a stale/crashed heartbeat is reclaimed by TTL.

Known follow-up

• Presence streams grow append-only (heartbeat every 30s). list_users reads a bounded recent window; retention/pruning is a future optimization (the seam has no delete) — noted, not blocking.

🤖 Generated with Claude Code