@sjawhar/opencode-legion-envoy 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {
@@ -21,14 +21,16 @@
   "files": [
     "dist",
     "src",
-    "!src/**/__tests__"
+    "!src/**/__tests__",
+    "skills"
   ],
   "scripts": {
     "build": "bun build src/server.ts bin/dispatch-mcp-shim.ts --outdir dist --target bun --format esm --external '@opencode-ai/*'",
-    "prepack": "bun run build",
+    "prepack": "bun run build && rm -rf skills && cp -r ../../skills skills",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
-    "lint": "bunx biome check src/"
+    "lint": "bunx biome check src/",
+    "postpack": "rm -rf skills"
   },
   "dependencies": {
     "@opencode-ai/plugin": "~1.14.46"

package/skills/AGENTS.md

@@ -0,0 +1,39 @@
+# Skills Layer
+
+Legion skills guide the architect and its sequential phase workers in a shared issue workspace.
+They are Markdown instructions loaded by Oh My Pi sessions; the daemon and OMP extension own
+event intake, process lifecycle, credentials, and role delivery.
+
+## Structure
+
+```
+skills/
+├── dispatch/            # Raising a durable human question as a GitHub-issue thread
+├── github/              # GitHub issue and pull-request operations
+├── linear/              # Linear adapter instructions
+├── legion-architect/    # Tree ownership, decomposition, gates, and scheduling
+├── legion-controller/   # Derived-verdict control-plane operation
+├── legion-oracle/       # Repository-grounded research
+├── legion-retro/        # Post-review retrospective
+└── legion-worker/       # Sequential architect, plan, implement, test, and review phases
+```
+
+## Phase workers
+
+The extension supplies a phase worker with its issue, workspace, role token, and structured
+output schema. The worker claims its supplied role, works only on its phase artifact, and
+returns that schema to the architect. It writes the same phase-specific payload to
+`.legion/<phase>.json`, verifies it exists, and commits the handoff before reporting completion.
+The committed predecessor handoff wins after revival or re-creation.
+
+Workers do not run a controller loop or mutate lifecycle labels. Workers coordinate
+lifecycle, scope, and cross-phase decisions with the owning architect through hub, sending
+the verified observation and decision needed. A worker may use the `dispatch` MCP tool
+directly for a durable human question; replies come back to the worker's own session.
+
+## Durable artifacts
+
+Phase handoffs are committed in lifecycle order: architect, plan, implement, test, and review.
+The reviewer removes `.legion/` as its final commit; retro records its learning in
+`docs/solutions/` and writes no handoff. GitHub comments and reviews carry the required Legion
+footer so the daemon can attribute artifacts to their worker session.

package/skills/dispatch/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: dispatch
+description: Use when you need a human decision from Sami or the user — asking a question, waiting on approval, saying "let me know", writing an end-of-message question block, picking between options with tradeoffs, or starting unattended/long-running work that will need input later. Raises the question as a durable GitHub-issue thread instead of a transcript question nobody will see.
+---
+
+# Dispatch
+
+`dispatch` turns a question into a durable, dashboard-visible GitHub-issue thread instead
+of a line buried in a transcript. Use it any time you would otherwise leave a question for
+a human to notice on their own.
+
+## When to dispatch
+
+- Any question not answerable at the keyboard in seconds.
+- Anything decision-shaped: a fork in approach, a tradeoff only the human can weigh, an
+  approval gate.
+- Anything you would otherwise write as an end-of-message question block and hope someone
+  reads.
+- Before you park on a blocker. Never leave a session idle on an unasked question.
+- Unattended or long-running work (Legion roles, background agents) that will need input
+  later — dispatch the question as soon as you know you'll need it, don't wait to be asked.
+
+## When NOT to dispatch
+
+- A one-word clarification the human is actively typing with you right now, in the same
+  turn — use the built-in `ask` tool instead. `dispatch` is for questions the reader has
+  not seen your transcript for; `ask` is for questions inside a live conversation.
+- Anything you can resolve yourself from tools or repo context. Dispatch is for genuine
+  human decisions, not a substitute for research.
+
+## How
+
+```
+dispatch({
+  subject:  "Postgres migration: run online or take a maintenance window?",
+  context:  "Implementing the users-table index migration for issue #482. The table has
+             40M rows; a plain CREATE INDEX locks writes for ~6 minutes in the staging
+             timing test I just ran.",
+  question: "Current: no online-migration tooling wired into this repo's deploy pipeline.
+             Desired: index added without a customer-visible write outage.
+             Option A — CREATE INDEX CONCURRENTLY, no lock, ~25 min, can't run inside a
+             transaction (rules out the existing migration runner without a change).
+             Option B — take a 6-minute maintenance window during the 03:00 UTC low-traffic
+             slot, keep the existing runner unchanged.
+             Recommendation: B — smaller blast radius, no migration-runner change, and the
+             window is well inside the existing maintenance SLA.",
+  urgency:  "med"
+})
+```
+
+- `subject`: one line, the decision — this is the issue title and the dashboard row.
+- `context` (required): what you are doing, what you found, why you are stuck. **The
+  reader has not seen your transcript** — never write "the list above," "those items," or
+  anything that assumes shared context. State it fresh.
+- `question` (required): current state → desired state → proposed change, then options
+  with tradeoffs, then your own recommendation. Don't just describe the fork — say which
+  branch you'd take and why.
+- `ask` (optional): a list of `{ question, header?, options: [{ label, description? }] }`
+  when the decision is a discrete set of choices. These render as buttons on the dashboard
+  — use this instead of asking the human to type a free-text answer when the answer really
+  is "pick one of N."
+- `urgency` (optional, default `med`):
+  - `low` — whenever it's convenient, no deadline pressure.
+  - `med` — needed today.
+  - `high` — blocking something that will stall soon if unanswered.
+  - `blocking` — you cannot proceed at all right now.
+- `repo` (optional): only pass this to target a **different** repo than your current
+  working directory's GitHub remote. The shim fills `repo` from cwd automatically —
+  omit it in the common case.
+- `parent` (optional): only set this when a real issue already exists to attach to —
+  `<n>` for an issue in the resolved repo, or `owner/name#<n>` to point at a specific
+  issue in another repo. For Legion roles, `parent` is the root issue you're working
+  under. Omitting it creates a standalone top-level thread; don't invent a parent that
+  doesn't exist.
+
+## After dispatching
+
+The reply arrives back in your own session as a steer — you do not fetch it. Keep every
+other non-blocked lane of work moving while you wait; a dispatch is not a reason to go
+idle. Never poll GitHub for the reply and never set up a watcher, cron, or retry loop to
+check on it — the delivery mechanism is already push-based. The issue URL returned by the
+tool (`{"thread": N, "url": "..."}`) is the durable record; you don't need to keep it
+anywhere else.
+
+If the tool errors because it can't resolve a repo (cwd has no GitHub remote and no
+qualified `parent`), pass `repo=owner/name` explicitly and retry.
+
+**Named risk:** a thread created in a repo where the Envoy GitHub App is not installed
+gets created successfully, but replies to it never route back to your session — you'll
+wait forever for a steer that can't arrive. Coverage is every repo under `sjawhar`, plus
+`acme-org/example-repo` and `acme-org/example-e2e` — the App is
+deliberately not installed org-wide. That list can change; to check a repo before relying
+on a reply, `gh api /repos/<owner>/<name>/installation` returns 200 when the App is
+installed there and 404 when it is not.

package/skills/envoy/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: envoy
+description: Use when subscribing sessions to Envoy topics, sending agent-to-agent messages, or reasoning about topic formats for Slack/GitHub/agent routing.
+---
+
+# Envoy
+
+Envoy is Legion's event-routing subsystem. It delivers Slack, GitHub, and agent-to-agent events to OpenCode sessions.
+
+## What the tools do
+
+- `envoy_subscribe(topics)` — make the current session RECEIVE future events on those topics
+- `envoy_unsubscribe(topics?)` — stop receiving some or all topics
+- `envoy_list()` — show the union of live local and persisted registry subscriptions, with each topic marked `live`, `registry`, or `both`
+- `envoy_send(session_id, message)` — SEND a message directly to another session
+
+## Topic formats
+
+### Agent-to-agent
+
+- Direct session route:
+  - `notifications.agent.<session_id>`
+
+Example:
+
+- `notifications.agent.ses_2e6ca3034ffejVikSZ8mDwk0mR`
+
+### Legion role claims
+
+- Role topic:
+  - `notifications.role.<role>`
+
+Legion agents receive through a daemon-minted role token. Claim the role for the current
+session with `envoy_role_set(role="<role>")`; claiming transfers its holder with
+last-claim-wins semantics. A claimant does not manually subscribe to its role topic.
+
+Legion role tokens must satisfy `^[a-z0-9][a-z0-9_-]*$` and are unique across repositories:
+
+```text
+legion-<project>-controller
+legion-<project>-<enc(owner)>__<enc(repo)>-<number>-<role>
+```
+
+`<project>` matches `[a-z0-9]+`. In owner and repository components, the injective escape
+encoding is `_` → `_u`, `.` → `_d`, and `-` → `_h`; `__` separates owner from repository.
+The daemon owns the authoritative token-to-issue map and hands the token to each process.
+Do not construct a token from a partial issue reference.
+
+Claims last through the issue's post-close linger. They survive parking and worker
+re-creation; a re-claim re-points the role to the backing session. The daemon publishes to an
+issue role only while the issue is active. Inactive issue events become daemon state and later
+surface as derived catch-up, never as raw event replay.
+
+### Legion exception lane
+
+`no_holder` and `delivery_failed` on a Legion role are daemon liveness signals, not a prompt
+for a second subscriber or a manual retry. The daemon probes the process that owns the tree:
+
+1. If it is alive, the daemon sends a control-topic directive. The extension revives or
+   re-creates the backing worker in code, then the daemon re-delivers the message.
+2. If it is dead, the daemon resurrects the root process behind a generation lock and supplies
+   derived catch-up plus the shared workspace handoffs.
+
+This keeps raw delivery failures out of architect context. Controller exception wakes are
+handled by the controller's wake routing table; every other role follows the liveness path.
+
+### GitHub
+
+GitHub topics are **resource-scoped** — every event includes the resource type and number (or, for push/workflow events, the ref or workflow filename).
+
+**Topic structure:** `notifications.github.<owner>.<repo>.<resource_type>.<number>.<event_kind>`
+
+- PR opened/closed/merged/ready:
+  - `notifications.github.<owner>.<repo>.pr.<number>`
+- Issue opened/closed/labeled:
+  - `notifications.github.<owner>.<repo>.issue.<number>`
+- Comment on a PR:
+  - `notifications.github.<owner>.<repo>.pr.<number>.comment`
+- Comment on an issue:
+  - `notifications.github.<owner>.<repo>.issue.<number>.comment`
+- PR review submitted:
+  - `notifications.github.<owner>.<repo>.pr.<number>.review`
+- Raw CI check observation (per-PR, immediate):
+  - `notifications.github.<owner>.<repo>.pr.<number>.check`
+  - Every PR-associated `check_run` publishes one raw observation per associated PR. `Payload` is JSON with `sha`, `name`, `status`, and `conclusion`; `PayloadSummary` names the check and its state.
+- CI/check summary (per-PR, per-commit, debounced):
+  - `notifications.github.<owner>.<repo>.pr.<number>.ci`
+  - The same `check_run` updates ingest-side per-commit state in JetStream KV bucket `envoy_ci_state`. Once the check set has been quiet for `ENVOY_CI_DEBOUNCE` (default `5s`), Envoy publishes one JSON summary. A new summary is emitted only when the check set changes; a new push starts a fresh tally, and a re-run that returns to running changes the tally.
+  - `PayloadSummary` is a compact JSON object (`Payload` unused): `{"kind":"ci_summary","repo":"<o>/<r>","number":"<n>","sha":"<sha>","failed":{"count":N,"checks":[...]},"running":{...},"passed":{...},"queued":{...},"skipped":{...}}`. Each status is `{count, checks}` with the full sorted name list; every status is present (`{"count":0,"checks":[]}` when empty).
+  - `check_suite` is ignored (it is a per-app rollup without a per-check name). Checks not tied to a PR are dropped, so there is no repo-wide CI topic. For non-PR visibility, use `workflow.<filename>.<action>`; individual GitHub Actions `workflow_job` events are not routed.
+- Mention events (per-resource):
+  - `notifications.github.<owner>.<repo>.pr.<number>.mention`
+  - `notifications.github.<owner>.<repo>.issue.<number>.mention`
+- Mention events (repo-wide — catches all mentions):
+  - `notifications.github.<owner>.<repo>.mention`
+- Push events (per branch/tag):
+  - `notifications.github.<owner>.<repo>.push.branch.<branch>`
+  - `notifications.github.<owner>.<repo>.push.tag.<tag>`
+  Branch and tag names with dots are sanitized to underscores (`v1.0.0` → `v1_0_0`).
+  Push events for refs other than `refs/heads/...` and `refs/tags/...` are not routed.
+- Workflow run events (per workflow file):
+  - `notifications.github.<owner>.<repo>.workflow.<filename>.<action>`
+  Filename is the basename of `workflow_run.path` with dots sanitized (`ci.yml` → `ci_yml`).
+  `action` is one of `requested`, `in_progress`, `completed`.
+
+**Using wildcards to subscribe broadly:**
+- All events in a repo: `notifications.github.<owner>.<repo>.>`
+- All PR events in a repo: `notifications.github.<owner>.<repo>.pr.>`
+- All events for a specific PR: `notifications.github.<owner>.<repo>.pr.<number>.>`
+- All issue events in a repo: `notifications.github.<owner>.<repo>.issue.>`
+- All events for a specific issue: `notifications.github.<owner>.<repo>.issue.<number>.>`
+- All push events in a repo: `notifications.github.<owner>.<repo>.push.>`
+- Pushes to main only: `notifications.github.<owner>.<repo>.push.branch.main`
+- All branch pushes: `notifications.github.<owner>.<repo>.push.branch.>`
+- All tag pushes: `notifications.github.<owner>.<repo>.push.tag.>`
+- All workflow events: `notifications.github.<owner>.<repo>.workflow.>`
+- All events for a specific workflow: `notifications.github.<owner>.<repo>.workflow.ci_yml.>`
+- Every workflow completion: `notifications.github.<owner>.<repo>.workflow.*.completed`
+
+Examples:
+
+- `notifications.github.example-org.example-repo.pr.9880` (PR #9880 state changes)
+- `notifications.github.example-org.example-repo.pr.9880.comment` (comments on PR #9880)
+- `notifications.github.example-org.example-repo.issue.9909.>` (all events on issue #9909)
+- `notifications.github.sjawhar.legion.pr.>` (all PR events across all PRs)
+- `notifications.github.sjawhar.legion.mention` (all @mentions repo-wide)
+- `notifications.github.sjawhar.legion.push.branch.main` (pushes to main)
+- `notifications.github.sjawhar.legion.workflow.ci_yml.in_progress` (CI workflow starts)
+
+### Slack
+
+- Channel message events:
+  - `notifications.slack.<team_id>.<channel_id>.message`
+- App mention events:
+  - `notifications.slack.<team_id>.<channel_id>.mention`
+- Thread message events:
+  - `notifications.slack.<team_id>.<channel_id>.thread.<normalized_ts>.message`
+- Thread mention events:
+  - `notifications.slack.<team_id>.<channel_id>.thread.<normalized_ts>.mention`
+
+Thread timestamps are normalized: `1234567890.123456` → `1234567890_123456`
+(dots replaced with underscores to make the thread ID a single NATS segment).
+
+Examples:
+
+- `notifications.slack.T01234567.C0A0DHVU8HE.message`
+- `notifications.slack.T01234567.C0A0DHVU8HE.mention`
+- `notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.message`
+- `notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.mention`
+
+### Ghost Wispr
+
+- Session started events:
+  - `notifications.ghostwispr.<session_id>.session.started`
+- Session ended events:
+  - `notifications.ghostwispr.<session_id>.session.ended`
+- Summary ready events:
+  - `notifications.ghostwispr.<session_id>.summary.ready`
+
+**Parameters:**
+- `<session_id>`: Ghost Wispr session timestamp string (e.g., `20260326041405`). Alphanumeric only, safe for NATS topic segments.
+- Supported kinds: `session.started`, `session.ended`, `summary.ready`
+
+Examples:
+
+- `notifications.ghostwispr.20260326041405.session.ended` (session ended)
+- `notifications.ghostwispr.20260326041629.summary.ready` (summary ready)
+
+### WhatsApp
+
+- Chat message events:
+  - `notifications.whatsapp.<phone>.<jid>.message`
+- Status/receipt events:
+  - `notifications.whatsapp.<phone>.<jid>.status`
+
+**Parameters:**
+- `<phone>`: Connected WhatsApp account phone number in E.164 digits-only format (no `+` prefix). Example: `15551234567`. This identifies **which WhatsApp account** the events belong to — not the remote contact.
+- `<jid>`: Remote chat's WhatsApp JID. Individual: `PHONE@s.whatsapp.net`. Group: `ID@g.us`.
+- Supported kinds: `message`, `status`
+
+> **⚠️ JID dot expansion:** JID dots (`.`) become additional NATS subject tokens. For example, `5551234567@s.whatsapp.net` splits into tokens `5551234567@s`, `whatsapp`, `net`. This means individual chat topics produce 7 tokens and group chat topics produce 6 tokens. **Always use `>` (multi-level wildcard), never `*` (single-token wildcard)**, when subscribing to a chat or phone number.
+
+Examples:
+
+- `notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message` (individual chat messages — note this expands to 7 NATS tokens)
+- `notifications.whatsapp.15551234567.120363XXX@g.us.message` (group chat messages — 6 NATS tokens)
+
+## When to use what
+
+### To receive future Slack/GitHub/WhatsApp events
+
+1. Decide the exact topic(s)
+2. Call `envoy_subscribe([...])`
+3. Optionally call `envoy_list()` to confirm
+
+### To talk directly to another agent/session
+
+1. Get the target session ID
+2. Call `envoy_send(session_id, message)`
+
+You do NOT need to subscribe in order to send or publish.
+
+**Session ids are not stable for the life of a conversation.** On OMP, `/fork` and `/handoff`
+re-mint the session id while the conversation continues (esc-esc rewinds also did, on omp
+18.1.0–18.1.2 only); the extension rebinds automatically and injects an `envoy` notice naming
+the previous and new ids. When that notice arrives, any id you shared earlier (an
+`envoy_whoami` result quoted in a message, an id a peer saved) is stale — re-run
+`envoy_whoami` and re-announce yourself. Never treat a whoami result from earlier in the
+transcript as current when identifying yourself to peers.
+
+### To wait for CI, PR checks, or other async work
+
+**Don't `sleep`-poll. Don't "check back in N minutes."** Subscribe to the event and continue with productive work — the system will wake the session when the event arrives.
+
+1. Identify the relevant topic (e.g., `notifications.github.<owner>.<repo>.pr.<num>.>` for all PR events; `.pr.<num>.check` for immediate per-check state; `.pr.<num>.ci` for the debounced PR summary; `.workflow.<filename>.completed` for a workflow run finishing)
+2. Call `envoy_subscribe([...])`
+3. Move on to other work, or end the response and let the watcher wake you
+4. The next response is triggered by the event, with the payload available in your context
+
+If you have nothing else to do, end the response. The user is not your alarm clock; do not loop with `sleep`.
+
+### Tools
+
+- `envoy_subscribe(topics)` — receive future events on those topics
+- `envoy_unsubscribe(topics?)` — stop receiving some or all topics
+- `envoy_list()` — show live and persisted subscriptions, marked by source
+- `envoy_send(session_id, message)` — send directly to a specific session (point-to-point)
+- `envoy_publish(topic, message)` — publish a normal topic to matching subscribers or route a role topic to its current holder
+- `envoy_role_set(role)` — claim a named role for the current session (exactly-one-holder)
+
+## Patterns
+
+### Subscribe controller to a specific Slack channel mentions
+
+```text
+envoy_subscribe([
+  "notifications.slack.T01234567.C0A0DHVU8HE.mention"
+])
+```
+
+### Subscribe to all events in a specific Slack thread
+
+```text
+envoy_subscribe([
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.>"
+])
+```
+
+### Subscribe to only messages in a Slack thread (not mentions)
+
+```text
+envoy_subscribe([
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.1234567890_123456.message"
+])
+```
+
+### Subscribe to all threads in a Slack channel
+
+```text
+envoy_subscribe([
+  "notifications.slack.T01234567.C0A0DHVU8HE.thread.>"
+])
+```
+
+### Subscribe to all PR events for example-repo
+
+```text
+envoy_subscribe([
+  "notifications.github.example-org.example-repo.pr.>"
+])
+```
+
+### Subscribe controller to GitHub @mentions for example-repo
+
+```text
+envoy_subscribe([
+  "notifications.github.example-org.example-repo.mention"
+])
+```
+
+### Message another session directly
+
+```text
+envoy_send(
+  session_id="ses_2e6ca3034ffejVikSZ8mDwk0mR",
+  message="Please continue the smoke test"
+)
+```
+
+### Subscribe to a specific WhatsApp contact (1:1 chat)
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>"
+])
+```
+
+Use `>` (not `*`) to catch all event kinds despite JID dot expansion into multiple NATS tokens.
+
+### Subscribe to a WhatsApp group
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.120363XXX@g.us.>"
+])
+```
+
+### Subscribe to all WhatsApp events for an account
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.>"
+])
+```
+
+Catches all conversations and event kinds for the specified phone number.
+
+**When to use which:**
+- **1:1 chat** — when monitoring a specific contact conversation (e.g., a bot handling customer queries)
+- **Group chat** — when monitoring a specific group for commands or events
+- **All chats for a phone** — when building a general WhatsApp event handler or dashboard for an account
+
+## Important notes
+
+- Sessions choose their own Slack/GitHub subscriptions
+- Different sessions can subscribe to different channels/repos
+- Agent-to-agent delivery uses exact session IDs
+- `envoy_list()` distinguishes `live`, `registry`, and `both`; a `live` topic is receiving now even when the listener registry has not caught up.
+- For Slack, use the real `team_id` in topics (for example `T01234567`), not a workspace slug like `acme`
+- GitHub mention routing is body-based because GitHub has no dedicated app mention webhook event
+
+## Synthetic Smoke Test (WhatsApp — NATS Routing Only)
+
+> **Important:** This procedure validates Envoy's NATS → listener → session delivery path using `envoy_publish`. It does **not** test real WhatsApp message ingestion. The generic MCP bridge (`packages/envoy/cmd/mcp/`) can bridge real WhatsApp events, but requires production configuration. See "Current Limitations" below.
+>
+> **Two sessions required:** `envoy_publish` sets `source_session` to the publishing session's ID. The listener skips delivering broadcasts back to the sender (`packages/envoy/cmd/listener/main.go`). You must subscribe in one session and publish from a different session.
+
+### Step 1: Subscribe to a WhatsApp topic (Session A)
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>"
+])
+```
+
+### Step 2: Verify subscription is active (Session A)
+
+```text
+envoy_list()
+```
+
+Confirm `notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>` appears as `live` or `both`.
+
+### Step 3: Publish a synthetic test envelope (Session B — a different session)
+
+```text
+envoy_publish(
+  topic="notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message",
+  message="Synthetic WhatsApp smoke test: hello from envoy_publish"
+)
+```
+
+### Step 4: Verify delivery (Session A)
+
+Session A should receive a notification containing the text "Synthetic WhatsApp smoke test: hello from envoy_publish". This confirms:
+- The topic pattern matches the subscription
+- NATS routes the message to the listener
+- The listener delivers to the subscribed session (Session A ≠ the publishing session)
+
+**If the notification does not arrive:** Check `envoy_list()` in Session A. The topic should be `live` or `both`; `registry` alone does not confirm the local subscription is receiving. Verify the topic in `envoy_publish` matches the subscription pattern. Ensure you are publishing from a **different** session than the one subscribed.
+
+### Reference: Real WhatsApp Envelope Shape
+
+When the MCP bridge (`packages/envoy/internal/mcpbridge/envelope.go`) publishes a real WhatsApp event, the Envoy envelope has this structure:
+
+```json
+{
+  "event_id": "<generated unique ID>",
+  "source": "whatsapp",
+  "source_event_id": "whatsapp://messages/15551234567/5551234567@s.whatsapp.net",
+  "topic": "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message",
+  "dedupe_key": "whatsapp.<event_id value>",
+  "issued_at": 1712345678000,
+  "payload_summary": "Hello from WhatsApp",
+  "payload_ref": "whatsapp://messages/15551234567/5551234567@s.whatsapp.net",
+  "trace_id": "<generated unique ID>"
+}
+```
+
+**Field notes:**
+- `source` is `"whatsapp"` — in contrast, `envoy_publish` sets `source: "agent"` for synthetic messages
+- `issued_at` is in **milliseconds** (Unix epoch ms), not seconds
+- `dedupe_key` is `source + "." + event_id` (e.g., `"whatsapp.cuid_abc123"`)
+- `payload_summary` is the actual message text from the MCP resource read (truncated to 200 chars), or fallback `"whatsapp event from <uri>"` if no text content
+- `payload_ref` and `source_event_id` are both the MCP resource notification URI
+- `source_session` is **omitted** (empty) — the MCP bridge is not an OpenCode session, so no echo-skip occurs
+- `expires_at` is **omitted** — the bridge does not set message expiry
+
+## Current Limitations (WhatsApp)
+
+- **No production WhatsApp event ingestion configured.** The repo contains a generic MCP→NATS bridge (`packages/envoy/cmd/mcp/` + `packages/envoy/internal/mcpbridge/`) that already supports WhatsApp topic patterns (tested in `packages/envoy/internal/integration/delivery_test.go`). However, it is not yet configured/deployed to connect to the `@sjawhar/whatsapp-mcp` server in production.
+- **Synthetic testing only.** The smoke test above uses `envoy_publish` to inject test messages into NATS. It validates Envoy delivery mechanics (NATS → listener → session), not true WhatsApp end-to-end delivery.
+- **Production wiring needed.** To receive real WhatsApp events, the MCP bridge needs to be configured with the `@sjawhar/whatsapp-mcp` server connection details (similar to how `packages/envoy/cmd/github/` and `packages/envoy/cmd/slack/` are configured for their respective platforms). The bridge would then subscribe to WhatsApp MCP resource notifications and publish Envoy envelopes to NATS automatically.
+- **Subscription + routing + delivery path is ready.** The contracts layer (`whatsappSubject` helper), NATS topic format, generic listener routing, and MCP bridge infrastructure all work. Only the production configuration connecting the bridge to the WhatsApp MCP server is missing.