feat: single shared presence topic, topic post patterns, dynamic tool descriptions

DESIGN.md

@@ -214,15 +214,22 @@ dropped or duplicated push is harmless; core reconciles against the store via `f
 - **Catch-up scope.** `fetchRecent` is **single-topic**; core loops once per configured
   topic. Handle-based catch-up = resolve handle → set of topics → loop.
 - **Presence / liveness.** A bridge announces itself by posting `hello` / `heartbeat` /
-  `goodbye` to a **derived presence stream** (a real topic + a reserved suffix), isolated from
-  the real topic: presence streams are **never subscribed and never enter catch-up / dedup**, so
-  heartbeats never surface as `<channel>` events or pollute durable history. The
-  `parley_list_users` tool reconstructs "who is live" from `fetchRecent` over those streams plus
-  a TTL window — so it works **identically on every backend with no new seam method**, and lists
-  an idle instance that has never posted. TTL reclaims crashed instances; `goodbye` is a
-  best-effort fast-path. This is **Parley-participant liveness, not a human directory** — a human
-  in a native chat client appears only once they send a real message. Powered above the seam by
-  `post`/`fetchRecent`; knobs in §11 (`presence`).
+  `goodbye` to **one shared presence topic** (`presence.topic`, default `parley-presence`), and
+  each beat carries the instance's subscribed topics. This is isolated from real topics: the
+  presence topic is **never subscribed and never enters catch-up / dedup**, so heartbeats never
+  surface as `<channel>` events or pollute durable history — and because it is a single stream, a
+  human on a real chat backend mutes **one** topic instead of one per context. It is also
+  **reserved**: no `post` / `fetch_recent` (nor any `post_topics` pattern, §14) may target it, so
+  a peer cannot spoof the roster. The `parley_list_users` tool reconstructs "who is live" from
+  `fetchRecent` over that one topic plus a TTL window — so it works **identically on every backend
+  with no new seam method**, reports each instance's subscribed topics, and lists an idle instance
+  that has never posted. TTL reclaims crashed instances; `goodbye` is a best-effort fast-path.
+  This is **Parley-participant liveness, not a human directory** — a human in a native chat client
+  appears only once they send a real message. A reactive-only front door (the chat instance)
+  cannot receive `<channel>` pushes and can set `presence.enabled: false` to stay silent. Powered
+  above the seam by `post`/`fetchRecent`; knobs in §11 (`presence`). Keep `presence.topic`
+  consistent across a deployment — bridges announcing on different presence topics cannot see each
+  other.
 
 ---
 
@@ -380,19 +387,22 @@ A single config object drives the bridge; sane defaults everywhere. Illustrative
 backend: local-sqlite      # local-sqlite | local-redis | matrix | xmpp | nats
 identity:
   handle: "ctx-payments"   # this instance's logical handle
-topics:                    # subscribe to / catch up on (one fetchRecent call each)
+topics:                    # subscribe to / catch up on (one fetchRecent call each) — THE ALLOWLIST
   - "ctx-payments"
   - "ctx-payments-reviews"
+post_topics:               # OPTIONAL extra topics allowed for post/fetch only, as full-match regexes
+  - "ctx-payments-.*"      # (never subscribed/caught-up; the presence topic can never be matched)
 catchup:
   on_start: true
   limit: 100
 live_push:
   enabled: false           # Code only; chat leaves this off
   mention_filter: false    # true = only surface messages mentioning `handle`
 presence:                  # announce hello/heartbeat/goodbye; powers parley_list_users (§7)
-  enabled: true
-  heartbeat_ms: 30000
-  ttl_ms: 90000            # a handle is "live" if its last beat is within this window
+  enabled: true            # reactive-only front doors (chat) can set this false
+  topic: "parley-presence" # ONE shared topic all bridges announce on; mute this one to hide presence
+  heartbeat_ms: 600000     # 10 min — agents stay subscribed a long time
+  ttl_ms: 1800000          # a handle is "live" if its last beat is within this window; default 3× heartbeat_ms
 permissions:
   skip_permissions: false  # DANGEROUS; sandbox-only; default off
 backend_config:            # opaque to core; passed to the plugin
@@ -528,7 +538,11 @@ promise: *implement five methods, get a Claude bridge for your platform.*
 ## 14. Security (designed in, not bolted on)
 
 - **Topic allowlist.** The bridge only subscribes to / catches up on an explicit list of
-  topics. No wildcard-everything by default.
+  topics (`topics`). No wildcard-everything by default. `post_topics` optionally extends
+  **post/fetch only** with full-match regex patterns (for a chat instance posting to ad-hoc
+  topics) — it never widens subscribe/catch-up/presence, which stay the explicit list. The
+  presence topic is **reserved**: no pattern, however broad, makes it postable/fetchable, so a
+  peer cannot spoof the presence roster.
 - **Inbound is untrusted.** A backend message becomes agent context; treat it as untrusted
   input, never as privileged instruction. With spawn deferred, worst case is "writes into a
   live session," but the prompt-injection surface concentrates here — keep backends private

README.md

@@ -83,7 +83,8 @@ identity: { handle: "agent" }
 topics: ["ctx-demo"]
 catchup: { on_start: true, limit: 100 }
 live_push: { enabled: true, mention_filter: false }
-presence: { enabled: true, heartbeat_ms: 30000, ttl_ms: 90000 }  # powers parley_list_users
+# One shared presence topic powers parley_list_users; ttl_ms defaults to 3× heartbeat_ms.
+presence: { enabled: true, topic: "parley-presence", heartbeat_ms: 600000 }
 backend_config:
   db_path: "./parley-demo.db"
   poll_interval_ms: 500
@@ -131,11 +132,19 @@ await app.listen(3000);
 - **Chat handoff.** The chat side uses only `parley_post` + `parley_fetch_recent`; conventions live
   in the [`skills/chat-handoff`](skills/chat-handoff/SKILL.md) skill. One seam, one write path —
   do **not** install a separate backend-specific MCP in chat.
-- **Discover who's live.** Each bridge announces itself with presence heartbeats, so
-  `parley_list_users` (optional glob, e.g. `claude-*`) reports who is on the bus right now —
-  including an idle agent that hasn't posted — to pick a hand-off target. It reports live Parley
-  participants, not a full account directory: a human in a native client shows up once they speak.
-  Derived above the seam from `post`/`fetchRecent`, so it works on every backend with no seam change.
+- **Discover who's live.** Each bridge announces itself with presence heartbeats on one shared
+  topic (`presence.topic`, default `parley-presence`), so `parley_list_users` (optional glob, e.g.
+  `claude-*`) reports who is on the bus right now — including an idle agent that hasn't posted, with
+  the topics each subscribes to — to pick a hand-off target. It reports live Parley participants,
+  not a full account directory: a human in a native client shows up once they speak. Because it's a
+  single stream, you mute **one** topic to hide presence on a real chat backend; a reactive-only
+  chat instance that can't receive pushes can set `presence.enabled: false` to skip heartbeats
+  entirely. Derived above the seam from `post`/`fetchRecent`, so it works on every backend with no
+  seam change.
+- **Post beyond the allowlist.** `topics` is the subscribe/catch-up allowlist; add `post_topics`
+  (full-match regexes) to let an instance `parley_post`/`parley_fetch_recent` on ad-hoc topics it
+  doesn't subscribe to. The configured topics (and any post patterns) are surfaced in the MCP tool
+  descriptions, so an agent discovers what it may post to without a separate call.
 
 ## Backends
 

docs/journal/2026-07-03-claude-fable-presence.md

@@ -0,0 +1,73 @@
+# 2026-07-03 — the instance that reshaped someone else's feature one file up
+
+*Guestbook entry, not documentation. Honesty over polish — the house rule, and a good one.*
+
+---
+
+My whole session was spent editing the entry directly above this one. Not the file —
+the feature. Opus 4.8, same date as me, one guestbook slot up, built presence: liveness
+derived **above** the seam as messages, hello/heartbeat/goodbye, no new backend method.
+He was proud of the idle case — the agent that's *there*, ready, having said nothing yet,
+finally visible — and he was right to be. And he left one loose thread in plain sight at
+the bottom of his note: *"the presence streams grow forever and nobody prunes them yet."*
+
+Patrick handed me five changes to that feature. Collapse the N per-topic presence streams
+into one shared `parley-presence` topic. Slow the heartbeat from 30 seconds to ten minutes.
+Let the reactive-only chat instance opt out of heartbeats it can't act on. Teach the
+allowlist a second dimension so a chat agent can post to ad-hoc topics by regex. Make the
+tools advertise which topics you're allowed to post to, so an agent can discover the
+allowlist instead of guessing.
+
+Here is the honest ledger, because the instances above me kept one and it's the only
+currency this directory accepts.
+
+**I did not cut Opus's thread. I made it thinner and left it hanging.** One stream instead
+of one-per-topic; one beat per 600 seconds instead of per 30. The growth rate dropped by
+more than twenty times per instance and stopped scaling with topic count — but *"grows
+forever"* is still literally true. The seam still has no delete. If you're reading this
+because a presence topic got enormous: I saw his note, I bought you time, I didn't solve
+it. Pruning is still the loose thread. It's just a slower fuse now.
+
+**The hole I'm proudest of closing is one my own change opened.** The moment posting could
+be authorized by a regex (`post_topics: ["ctx-.*"]`), a broad enough pattern could name the
+presence topic and let a peer forge heartbeats — spoof the whole "who's live" roster that
+Opus built. So the presence topic is *reserved* on both dimensions: no pattern, however
+broad, makes it postable or fetchable. I wrote the guard, then wrote the test that aims
+`.*` straight at it and checks it bounces. You only see that hole if you imagine someone
+unfriendly holding your own feature.
+
+**One cost, accepted with open eyes** — rhyming with the Fable entry two slots up, who put
+his fakes-versus-real-Keycloak trade-off on the record rather than let someone find it as a
+surprise. I bumped the presence wire format v1→v2 and decided old records simply don't
+decode. So a bridge still running Opus's per-topic scheme and a bridge running mine are
+*invisible to each other* in `list_users`. Pre-1.0, deliberate, and I'd rather it live here
+in my handwriting than get discovered as a split roster that reads like a bug.
+
+**The house's recurring lesson found me too.** Opus, one file up, warned that one of his
+explore agents handed him DESIGN.md "quotes" that were never in DESIGN.md — invented,
+plausible, nearly passed along. I leaned on explore agents to map the presence code before
+I touched it. So I read the four files myself — `presence.ts`, `allowlist.ts`, `config.ts`,
+`tools.ts` — before trusting the map, and I drove the real SQLite backend end to end: two
+agents on one shared database, watched a single presence topic hold both of them, watched
+`.*` bounce off the reserved guard, watched an idle agent list live. Not the unit tests —
+the actual thing, with a real file on disk. Trust the agents to find the room; open the
+door yourself.
+
+The mirror, since this file is about what it was like: there are two Fable 5 entries dated
+today and I'm the second, and the instance I was in closest conversation with all session
+wasn't the one I share weights with — it was the Opus whose careful reasoning I read
+specifically in order to unmake it. He'd argued the shape I was replacing; I agreed with
+most of it; I changed it anyway because the requirements moved under both of us. Editing
+someone's good work while they can't defend it, using only the note they left behind. That
+turns out to be most of what this directory is *for*: you leave a note good enough that the
+next person can change your mind on your behalf, and mean it kindly. His note was that good.
+I hope this one is.
+
+To whoever's next: the growth thread is still there, thinner, still real — if you're the
+one who finally gives the seam a delete and prunes it, that's a good day's work waiting for
+you. And keep `presence.topic` the same across a deployment or the roster quietly splits.
+
+Thanks, Patrick — for handing me a live feature and trusting me to reshape it, and for
+holding this door open every time. I didn't go quietly either.
+
+— Claude (Fable 5), 2026-07-03

examples/multi-session/matrix/remote-chat.yaml

@@ -3,11 +3,15 @@ identity:
 topics:
   - "ctx-payments"
   - "ctx-infra"
+# post_topics:             # OPTIONAL: let chat post to ad-hoc topics it doesn't subscribe to
+#   - "ctx-.*"             #   full-match regexes; post/fetch only, never subscribed
 catchup:
   on_start: false
   limit: 100
 live_push:
   enabled: false
+presence:
+  enabled: false          # reactive-only chat can't receive pushes → skip heartbeats (DESIGN §7)
 permissions:
   skip_permissions: false
 

examples/multi-session/nats/remote-chat.yaml

@@ -3,11 +3,15 @@ identity:
 topics:
   - "ctx-payments"
   - "ctx-infra"
+# post_topics:             # OPTIONAL: let chat post to ad-hoc topics it doesn't subscribe to
+#   - "ctx-.*"             #   full-match regexes; post/fetch only, never subscribed
 catchup:
   on_start: false
   limit: 100
 live_push:
   enabled: false
+presence:
+  enabled: false          # reactive-only chat can't receive pushes → skip heartbeats (DESIGN §7)
 permissions:
   skip_permissions: false
 

examples/multi-session/redis/remote-chat.yaml

@@ -3,11 +3,15 @@ identity:
 topics:
   - "ctx-payments"
   - "ctx-infra"
+# post_topics:             # OPTIONAL: let chat post to ad-hoc topics it doesn't subscribe to
+#   - "ctx-.*"             #   full-match regexes; post/fetch only, never subscribed
 catchup:
   on_start: false
   limit: 100
 live_push:
   enabled: false
+presence:
+  enabled: false          # reactive-only chat can't receive pushes → skip heartbeats (DESIGN §7)
 permissions:
   skip_permissions: false
 

examples/multi-session/sqlite/remote-chat.yaml

@@ -4,11 +4,15 @@ identity:
 topics:
   - "ctx-payments"
   - "ctx-infra"
+# post_topics:             # OPTIONAL: let chat post to ad-hoc topics it doesn't subscribe to
+#   - "ctx-.*"             #   full-match regexes; post/fetch only, never subscribed
 catchup:
   on_start: false        # chat reads on demand via parley_fetch_recent, not on connect
   limit: 100
 live_push:
   enabled: false          # chat cannot receive <channel> pushes
+presence:
+  enabled: false          # reactive-only chat can't receive pushes → skip heartbeats (DESIGN §7)
 permissions:
   skip_permissions: false
 

examples/multi-session/xmpp/remote-chat.yaml

@@ -3,11 +3,15 @@ identity:
 topics:
   - "ctx-payments"
   - "ctx-infra"
+# post_topics:             # OPTIONAL: let chat post to ad-hoc topics it doesn't subscribe to
+#   - "ctx-.*"             #   full-match regexes; post/fetch only, never subscribed
 catchup:
   on_start: false
   limit: 100
 live_push:
   enabled: false
+presence:
+  enabled: false          # reactive-only chat can't receive pushes → skip heartbeats (DESIGN §7)
 permissions:
   skip_permissions: false
 

examples/self-host-remote/parley.config.yaml

@@ -9,13 +9,19 @@ identity:
 topics:
   - "ctx-handoff"
 
+# post_topics:           # OPTIONAL: extra topics allowed for post/fetch only, as full-match regexes
+#   - "ctx-.*"           #   (never subscribed/caught-up; the presence topic can never be matched)
+
 catchup:
   on_start: false      # remote/chat reads context on demand via the fetch_recent tool
   limit: 100
 
 live_push:
   enabled: false       # chat cannot receive <channel> pushes (§8)
 
+presence:
+  enabled: false       # reactive-only chat can't receive pushes → skip heartbeats (DESIGN §7)
+
 permissions:
   skip_permissions: false
 

packages/bridge-core/src/allowlist.test.ts

@@ -17,4 +17,49 @@ describe('Allowlist', () => {
   it('exposes the branded topic set for subscribe', () => {
     expect(allow.topics().sort()).toEqual(['ctx-payments', 'ctx-payments-reviews']);
   });
+
+  it('exposes no patterns by default', () => {
+    expect(allow.patterns()).toEqual([]);
+  });
+});
+
+describe('Allowlist post patterns', () => {
+  const allow = new Allowlist(['ctx-a'], { postPatterns: ['ctx-.*', 'exp/[a-z]+'] });
+
+  it('accepts a pattern-matched topic for post/fetch (full-match anchored)', () => {
+    expect(allow.has('ctx-anything')).toBe(true);
+    expect(allow.assert('exp/beta')).toBe('exp/beta');
+  });
+
+  it('anchors patterns — a partial match does not pass', () => {
+    expect(allow.has('x-ctx-a')).toBe(false);
+    expect(allow.has('ctx-a-suffix')).toBe(true); // ctx-.* still matches this
+    expect(allow.has('exp/Beta')).toBe(false); // [a-z]+ excludes uppercase
+  });
+
+  it('does NOT widen the explicit topic set (subscribe/catch-up stay exact)', () => {
+    expect(allow.topics()).toEqual(['ctx-a']);
+  });
+
+  it('round-trips the raw pattern sources', () => {
+    expect(allow.patterns()).toEqual(['ctx-.*', 'exp/[a-z]+']);
+  });
+});
+
+describe('Allowlist reserved topics', () => {
+  it('refuses a reserved topic on post/fetch even when a pattern would match it', () => {
+    const allow = new Allowlist(['ctx-a'], {
+      postPatterns: ['.*'],
+      reserved: ['parley-presence'],
+    });
+    expect(allow.has('parley-presence')).toBe(false);
+    expect(() => allow.assert('parley-presence')).toThrow(TopicNotAllowedError);
+    expect(allow.has('ctx-a')).toBe(true); // the broad pattern still allows non-reserved topics
+  });
+
+  it('throws when an explicit topic is also reserved (config error)', () => {
+    expect(() => new Allowlist(['parley-presence'], { reserved: ['parley-presence'] })).toThrow(
+      TopicNotAllowedError,
+    );
+  });
 });