@sjawhar/claude-envoy 0.0.0 → 1.0.0

package/skills/dispatch/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dispatch
+description: "Use before your first dispatch command in a session: a message, comment, ask, artifact, document edit, claim or status change."
+---
+
+# Dispatch
+
+Dispatch is a record for the people who decide, never a log of your work.
+
+- Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
+- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`); give object and list fields as JSON.
+- Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
+
+## Asks and ask blocks
+
+- A design question a document records is an ask block (a decision block) at the end of its section:
+
+```md
+:::ask{urgency="med"}
+The question and the recommendation, as `skill://dispatch-writing-specs` writes them.
+
+- Option one: what it costs.
+- Option two: what it costs.
+:::
+```
+
+- An ask is short and asks one thing; its reasoning goes in the document.
+- An open ask is the request; never repeat it per message.
+- Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
+- Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` (a progress note) needs it. An approval request a newer version moved needs `request-approval` again.
+- When an answer's option and text disagree, the text wins.
+- An ask block has a block id, for `doc-edit`, and an ask id, for the ask commands. `dispatch read --ref dispatch://KEY/ask/<id>` takes either.
+- An ask reaches the issue's assignee; if none, name who answers.
+
+## Choosing what to work on
+
+- When you finish an issue, take the top ready one: `todo`, by priority then board rank, per project.
+- `todo` means specced and waiting on nothing; one that waits goes in `backlog`, saying on what.
+- Hold at most three issues in flight; move the rest to `backlog`, saying where each is.
+- Never reorder the board: one agent keeps each project's order (`issue-update --before`/`--after`). If the top looks wrong, tell `notifications.role.legion-<project>-controller`.
+
+## Issue status is yours to move
+
+Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. Never write or route the status of an issue with the `legion` label or under one, and claim one only as a role of its tree: an outside claim can take the tree out of the workflow. A status write is set back or stands.
+
+`unresponsive` holders keep their claims 20 minutes (`skill://envoy`).
+
+A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on release), brings a person's answers, comments and messages; for agents' activity, `envoy_subscribe notifications.dispatch.issue.<KEY>.>`, which shows no quiet event.
+
+## Close what you opened
+
+- Resolve your open ask (`dispatch resolve-ask`) the turn it turns needless: another answer, a later write, dropped work, a replacement. If a person said keep it open, say why in its thread; they close it.
+
+## Structure over stream
+
+- One issue per deliverable, its content the issue's document.
+- A message replies to a person or tells them what they must know now.
+- Text a person must read to decide belongs in the spec. An artifact is a real file.
+
+## Architecture components
+
+Attach each architectural issue to its components (`--components-json`), the root before decomposing it. Change code and `.dispatch/architecture/<id>.md` in the same review.
+
+## References
+
+Link each item you name:
+
+```text
+dispatch://KEY
+dispatch://KEY/spec
+dispatch://KEY/spec#b-<block>[@vN]
+dispatch://KEY/artifact/<slug>[@vN]
+dispatch://KEY/ask/<id>
+dispatch://KEY/ask/<id>#b-<part>[@vN]
+dispatch://KEY/comment/<id>
+dispatch://KEY/comment/<id>#b-<block>[@vN]
+dispatch://KEY/message/<id>
+dispatch://KEY/message/<id>#b-<block>
+dispatch://PROJECT/artifact/<slug>[@vN]
+dispatch://PROJECT/artifact/<slug>/ask/<id>
+dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
+```
+
+A bare id, filename or path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole.
+
+## Setup and the HTTP API
+
+- Use a personal token from **Settings → Agent tokens**, as `DISPATCH_TOKEN` or `dispatch.token` in the session's `envoy.json`.
+- `GET /api/v1` lists every route; never guess one. Branch on an error's `code`, not its text.

package/skills/dispatch-first/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: dispatch-first
+description: "Use when a session has the dispatch command, before you plan, file an issue, ask a human, post a finding, or start work. Someone may track that work already or hold a decision on it."
+---
+
+# Dispatch first
+
+Dispatch holds the open issues, their specs and people's answers.
+
+## Search before you act
+
+- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search`.
+- Each query word must match. Use two or three words: the thing and what is wrong with it. Never paste a draft.
+
+```bash
+dispatch search --query 'broadcast send order'
+dispatch search --query 'reviewer threads OR review comments'
+```
+
+- No hits: remove a word before you add one. Try two or three wordings before you decide nothing exists.
+- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`).
+
+## What to do with what you find
+
+`dispatch issue` and `dispatch ask` also search. Treat a hit in `advice.suggestions` as yours to read.
+
+- **Work already tracked:** put the finding on that issue. File a new issue only when no hit covers the work, and cite the nearest one you ruled out (`dispatch://KEY`).
+- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
+- **Duplicate found:** keep the issue with the spec, copy to it what only the duplicate has, and close the duplicate (`--status done --reason 'Duplicate of dispatch://KEY.'`). When it has the `legion` label or another holder's claim, comment the kept issue's name on it instead.
+
+## Reach a person only through Dispatch
+
+Reach a person through an ask, an ask block or an approval request.
+
+- The moment a person blocks your work, open an ask: an ask block for a design question its document records, else `dispatch ask`. A blocker that is not an open ask does not exist for them. A Legion phase worker sends decisions to its architect instead. Before you say you wait on a person, run `dispatch open-asks`.
+- A result a person asked for is the same: a document or artifact notifies nobody. End that document with an ask block asking their next step, else `dispatch ask`.
+- Record every request you accept in Dispatch before you start it: an issue, or a line in your issue's `open-items.md` artifact. Before you end a turn, read that record. Each item is done, in progress, or an open ask. Never drop one.
+
+## Which skill to read
+
+| Before you | Read |
+| --- | --- |
+| run your first `dispatch` command in this session | `skill://dispatch` |
+| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs` |
+| plan work whose spec a person approved | superpowers' `writing-plans`, stored as the issue's `plan.md` (`skill://dispatch-writing-specs`, "The plan") |
+| write a Legion architect's own spec | `skill://legion-architect` too |

package/skills/dispatch-writing-specs/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: dispatch-writing-specs
+description: "Use in a session with Dispatch before you write or change a spec, ask, comment or message a person reads. It replaces superpowers' brainstorming there."
+---
+
+# Writing specs
+
+## The conversation
+
+Reach shared understanding with the person at the least cost of their time. A spec is a conversation, not a document you write and then ask about. A Legion phase worker writes none (`skill://legion-worker`). In order:
+
+1. Read the issue, the code and what the person wrote.
+2. Send what you found and the questions it leaves open, a few at a time, before the spec states a design.
+3. Write each part only after the answers it rests on.
+4. A wrong premise or a changed request changes the request first.
+
+## The outline
+
+Find the issue's project with `dispatch projects` or `search`, never the environment. The spec's `##` parts, in order:
+
+Part | Content
+--- | ---
+`Summary` | The change in the reader's terms, at most 100 words
+`Problem` | What goes wrong, for whom, with counts
+`Goals and non-goals` | What is in and out of scope
+`Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
+`Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run`, `when`, `negative_control`
+`Design` | How it meets them; a value and its reason for each limit, size and time
+`Decisions` | One line: `The decisions are in dispatch://KEY/artifact/decisions-md.`
+
+`serves` and `needs` name a block of this issue or an ancestor. Another agent can build and check the work from these alone. A small change gets a few sentences per part, no matrix; split a large design into child issues.
+
+## Rules for the text
+
+For each spec, ask, comment and message:
+
+- Write in `skill://asd-ste100`'s strict mode.
+- Write about the current design, never the person or how people reached it, and never quote or upload their words.
+- Link each source where the person wrote it, each id whole. With no link, state the design.
+- In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
+- A sentence that cites a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
+- Keep only text that helps a reader understand, decide, build, check.
+- Explain each name a new reader may not know, and what each issue you name does for them.
+- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
+
+## Questions
+
+- Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
+- A choice inside what the person asked for, or one their messages favour, is yours.
+- Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
+- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone.
+
+## Each version
+
+1. After a person's answer, comment or edit, reread the problem and rewrite what the answer touches, deleting what it contradicts: an answer is integrated, never appended. Answer each comment in its thread. Never narrate an edit: versions and comments hold the history.
+2. Before each spec write, paste the whole spec, never a path, into a fresh subagent: it lists gaps, conflicts, uncheckable requirements, unclear text and needless questions. Fix or record each.
+3. Before each approval request, `wait` for a read-only fact check: `task(agent="scout")`.
+4. Name each version with `dispatch doc-edit --summary`.
+
+## Decisions
+
+Choices—answered asks included—earn `decisions.md` `##` sections only if a disagreeing reader would act differently; keep others to one spec line each.
+
+- The heading names the choice; the text gives the reason and the options weighed.
+- Link each spec block it shaped, `dispatch://KEY/spec#b-<id>`, and a person's decision its ask, `dispatch://KEY/ask/<id>`.
+- An unsure section adds a paragraph that starts `Unsure:`: what would change your mind.
+- A replaced section moves under a final `## Replaced` as a `###`.
+
+## Old specs
+
+Rewrite a spec outside the outline whole in one version, its ask blocks moved with `doc-edit`'s `move`; restate each retelling, quotation or unlinked attribution as design, or cut it.
+
+## Approval
+
+- Request approval of the spec and `verification.md` (`--include-verification`): each ask block answered or waived, each claim checked, this version unapproved. An unrun check never delays it.
+- After approval, version only a change to scope, a check, cost, risk or a person's decision, all at once; put other fixes in the plan or a comment. An exact undo can restore approval.
+
+## The plan
+
+Write the plan with `writing-plans` as the issue's `plan.md`, not a repository file. Each task is a `:::plan_task` block with `serves` and `needs`.

package/skills/envoy/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: envoy
+description: Use when you send a message to another agent session, reply to an Envoy delivery, find your own or a peer's session id, subscribe to a topic (a GitHub pull request, CI checks, a Dispatch issue, Slack), publish to a role or team topic, or wait for CI or a merge. Also when you are a subagent that must report to another session, or a subscription stays silent.
+---
+
+# Envoy
+
+If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
+
+Envoy delivers external events and messages between sessions. Delivery is at-least-once and can come out of order across topics: drop a repeated `id`, and when two deliveries conflict, act on the one with the later `at`.
+
+## Send a message to another session
+
+- Take the target id from the delivery's `reply_with`, or from `envoy_sessions` (filter by `machine`, `dir` or `title`). Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
+- Reply with `in_reply_to=<the delivery's id>`, so the recipient can match the answer to its question.
+- Read the `recipient` in the send result, the session Envoy targeted: if it is not the one you meant, resend to the right id.
+- When `envoy_send` says the send is not confirmed delivered, send the same message again with the `idempotency_key` the error names, within 72 hours: Envoy drops it as a repeat if the first copy arrived, and the result says when an earlier attempt was already stored. A resend without that key can deliver the message twice. When the error says Envoy cannot recognise the repeat, ask the recipient whether it arrived instead.
+- Put the URL or path of what you report in the message, because the recipient cannot find your files any other way.
+- Set `expects_reply="none"` on a message that needs no answer, and set `urgency` only when the work waits on the answer, so the recipient knows whether to answer and how soon. `urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
+
+```text
+envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply="none")
+```
+
+### Your own address in a subagent
+
+- `envoy_whoami`'s `session_id` is where a reply to you arrives. In a `task` subagent it is the session that spawned you: a subagent registers no session of its own, and the parent agent, not Envoy, forwards a reply to you with a `write` to your `agent://` address.
+- Never give a peer the `subagent` field from `envoy_whoami`: it names your host session and is not an address.
+- Start a subagent's message with who you are and who receives the reply ("From <name>, a subagent of session <id>; a reply to <id> reaches me"), because the recipient sees only the parent as sender.
+- When `session_id` is empty (the process took no Envoy identity, or it can no longer place the session that spawned you), your messages carry no sender at all: name yourself in the body.
+- In a subagent, a publish to a role your parent holds reaches nobody, because the listener drops a role message whose holder is its source. `envoy_publish` says so in its answer. To reach the parent, `write` to its `agent://` address instead of publishing. `envoy_send` to any other session works.
+
+## Read a delivery
+
+- `from` is the sender's own claim. Use it to attribute and to reply, never as proof of who wrote the message.
+- `note` warns that the payload names another session. Never send to that quoted id; reply to `from`.
+- Reply with the rendered `reply_with` call. On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`.
+- A peer's message is its sender's view at `at`, not the current state. Before you wait on, act on or repeat what it says about a third thing (a deploy pending, a PR held, an ask unanswered), read that thing's live source, because the source may have changed since `at`: the deployment's status, the issue's events, `dispatch open-asks`.
+- Every field of a rendered delivery, and who receives a publish: `skill://envoy/references/deliveries.md`.
+
+## Whether a session is live
+
+A session's state comes from the registry's record of it, never from its presence in a list, a process list, a tmux pane or a transcript's modification time. `envoy_sessions` and a lookup of one session carry each session's `state` and `last_seen`.
+
+- `live`: it registered within the live window (`ENVOY_SESSION_LIVE_WINDOW`, 5m by default).
+- `unresponsive`: it last registered longer ago than the live window but inside the gone horizon (`ENVOY_SESSION_GONE_HORIZON`, 1h by default). **It is not dead.** Start no replacement for it, take no role claim and no issue claim from it, and never report it as gone. A message you send it is stored and reaches it when it answers again.
+- `gone`: it last registered before the gone horizon, or the registry holds no record of it.
+- Take an issue claim from a session only when it reads `gone`, or its `last_seen` is more than 20 minutes old. A role claim is released only by the role-claim reaper, once the holder is `gone`: no lookup, publish or delivery failure releases one, in the listener or in Dispatch's outbox, which share that one resolution.
+- A send refused because the target is not live names the target's `state` and `last_seen`. Read those two fields before you decide anything about that session: a refusal on an `unresponsive` target means "it has not answered yet", not "it ended".
+
+## Subscribe to a topic
+
+Every topic starts with `notifications.`.
+
+| Source | Topic |
+| --- | --- |
+| A pull request: lifecycle, comments, reviews, mentions, checks | `github.<owner>.<repo>.pr.<n>.>` |
+| Other GitHub | `github.<owner>.<repo>.issue.<n>[.comment\|.mention]`, `.push.branch.<name>`, `.push.tag.<name>`, `.workflow.<file>.<action>` |
+| A Dispatch issue or document | `dispatch.issue.<KEY>.>`, `dispatch.document.<PROJECT>.<SLUG>.>` |
+| Your own inbox | `agent.<session_id>` |
+| Slack, Ghost Wispr, WhatsApp | `skill://envoy/references/sources.md` |
+
+- Write the owner, the repository, a branch or tag name and a workflow file as one token each, with every dot written `_`: `acme/site.io` is `github.acme.site_io`, and `ci.yml` is `workflow.ci_yml`. A slash stays. A topic spelled with the dot receives nothing.
+- Subscribe to the pull request's whole family, `pr.<n>.>`. Envoy also subscribes you to the lifecycle subject `pr.<n>`, which NATS `>` alone does not match, because `>` needs one or more trailing tokens.
+- Read the `warnings` that `envoy_subscribe` returns, and confirm the active topics with `envoy_list`. A warning names the spelling Envoy publishes, or a token that is not a GitHub topic kind; fix the topic it names. "No GitHub event ... in the stream's retention window" means nothing came from that repository in the last 72 hours: check that the GitHub App that sends Envoy its webhooks is installed on that repository before you rely on a wake.
+
+## Wait for CI or a merge
+
+- Subscribe to `github.<owner>.<repo>.pr.<n>.>` and end the turn. Never start a `gh` poller: the event wakes you, and a poller burns turns.
+- One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not. Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first. A commit whose message carries one of GitHub's skip keywords (`[skip ci]` and its kin) starts no workflow, so no settlement of it may ever arrive.
+- Settlement waits until the commit has had no check event for 5 seconds (`ENVOY_CI_DEBOUNCE`) and every reported check run and check suite of it has finished. No event arrives before that. Envoy does not read GitHub's required-checks list, so a green settlement does not mean GitHub will merge the PR.
+- A `pr.<n>` event with `closed` and `merged: true` means the PR merged; it carries `merge_commit_sha`, `merged_by` and `head_sha`.
+- A later settlement of the same commit can carry `superseded_settlement: "true"`. Code that orders settlements follows `skill://envoy/references/check-settlement.md`.
+- A Legion implementer waits this way only on a re-run of a red check its task names. Otherwise it pushes and completes its phase, and the daemon reads CI for it (`skill://legion-worker`).
+
+## Roles and team topics
+
+- Send to one session with `envoy_send`, to the one session that holds a named duty with a role, and to a group with a team topic.
+- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns once the holder's session confirmed it, with the live `holder` and its `holder_state`. When nobody holds the role, Envoy keeps the message for the session that claims the role next: the answer says it was kept, and that session is handed it once, within one hour of the keep. A holder that is not `live` returns an error instead: that refusal names the holder, its `holder_state` (`unresponsive` or `gone`), its `last_seen` and `claim_released: false`, and nothing was forwarded and nothing kept, so publish the message again once the holder answers rather than starting a replacement for it or taking anything from it. A live holder that did not confirm the message within about 4 seconds errs too, and you see that one after about 8 seconds, because the client tries once more. No error releases the role's claim: a holder whose `holder_state` is `unresponsive` keeps its role. `envoy_role_get(role=...)` finds the holder first. The stream keeps a forward on the holder's inbox, so a holder that was forwarded to gets it once from its own durable consumer, also after a restart or a reconnect.
+- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches every session subscribed when it is published, yours too when you subscribe. The listener also asks each other session that holds its own NATS connection and registered the topic (every session that follows it with `envoy_subscribe`) to confirm the message; your own session is never asked. A publish returns an error naming each such session that did not confirm within about 4 seconds, and you see it after about 8 seconds, because the client tries once more. A session named with `receipt_timeout` still gets the message: the listener kept a copy in that session's inbox, which the session reads back once its connection returns. An `unresponsive` session is sent the message the same way, asked for no receipt and named under `unresponsive` in the answer, which is no failure. A session that stopped without unregistering stays in the registry until the reaper finds it `gone`, and is named until then; a named session is not a failed delivery to the others. A team topic is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
+- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
+- In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.

package/skills/envoy/references/check-settlement.md

@@ -0,0 +1,62 @@
+# Ordering pull request check settlements
+
+Read this when you write or review code that consumes `pr.<n>.checks` settlements and must decide which of several settlements of one commit is current.
+
+## What a settlement carries
+
+- A commit can settle more than once. A later settlement can carry `superseded_settlement: "true"`, and an exact copy can arrive, because delivery is at-least-once.
+- `check_runs`, the attempt set: the latest GitHub check-run id per check name, sorted by name.
+- `generation`: the listener record's state version. `snapshot`: the record's hash.
+- A head publishes only when at least one check has a positive run id. Legacy checks without one appear in the status groups and the failing names, never in `check_runs`.
+
+## Order two attempt sets of one commit
+
+Compare the ids of the names both sets share:
+
+1. No id lower, and some id higher or a new name: newer. A new name counts as higher.
+2. Every shared id equal and no new name: the same set.
+3. No id higher, no new name, and some id lower: older.
+4. Anything else (a higher or new id alongside a lower one): a mixed view. Drop it as a conflict.
+
+Ignore names that only the stored set has: a check can vanish from GitHub's view, and a record recreated after the seven-day KV TTL starts sparse.
+
+## Keep a fence
+
+- The fence is the per-name maximum id over every set you accepted. Merge each accepted set into it, and prune nothing.
+- Within one listener record, per-name ids never decrease, so the fence never decreases either.
+- So a newer attempt is newer whatever its completion time, no timestamp takes part in ordering, and a name an incomplete view left out cannot later come back as new.
+
+## At the same set, order by generation
+
+- A lower `generation` is stale.
+- An equal `generation` with the same `snapshot` is a duplicate. With a different `snapshot`, drop it as a conflict: that pair occurs only when a record was recreated and reused a generation.
+
+## Apply a live settlement
+
+- A live settlement (one the listener sent) may be an incomplete view of the head: a webhook was missed, or the record was recreated after the KV TTL.
+- It decides the outcome of every name it reports, at any id the ordering accepted, the same run seen in place included. It says nothing about the names it leaves out.
+- A known failure among the names it leaves out stands, because you keep failure names, not a per-name status map. The head is red while any failure remains.
+
+## Reconcile with GitHub's rollup
+
+- Compare the rollup's attempt set in the same way. GitHub's read is complete: its failing check runs and failing commit statuses replace the stored ones wholesale.
+- Keep commit statuses apart from check-run failures, because statuses have no check run and the listener never sees them. A check run with a status's name cannot retire that status; only GitHub's read can. The same holds for a deleted check's failure.
+- A newer rollup set merges into the fence and takes the identity, with no listener generation.
+- The same set applies GitHub's verdict and keeps the listener identity for duplicate detection.
+- Ignore an older set, a mixed set, and an empty set when the fence already holds ids.
+
+## After a terminal GitHub read
+
+A terminal read is a green or red one. GitHub's verdict then holds authority at that set:
+
+- Accept a live settlement at the same set only if its effective outcome agrees with GitHub's verdict. The effective outcome is the check-run failures it reports, plus the stored ones it leaves out, plus the stored commit-status failures. Accepting it refreshes the listener identity, and GitHub's verdict keeps its authority.
+- A live settlement that disagrees is stale, whatever its generation, until the set advances.
+- A pending or cancelled-only read takes the green off a green head, leaves a red head red, and ends GitHub's authority at that set. The next terminal live settlement then applies at once, under the usual generation and duplicate rules: a replay or a lower generation still does not apply.
+- So the order of reads matters: a pending read after a live green takes the green off until the next terminal view.
+
+## Known gaps
+
+- A run whose conclusion changes in place, on the same run id: GitHub's view stands. The listener's view comes back with the next successful, non-skipped read at that set; the dropped delivery is not replayed.
+- A check whose highest run is deleted on GitHub: the fence keeps that id, so a rollup that reports a lower run under that name is older until a newer run appears.
+- A consumer that orders head changes by the PR's `updated_at` (one-second resolution) accepts a read of another head at an equal clock. A stale read that returns the previous head in the same second as its replacement rewinds that consumer until its next accurate, non-skipped read.
+- A legacy in-progress check whose completion is never seen holds the head unsettled until it reruns: rerun that check to release it.

package/skills/envoy/references/deliveries.md

@@ -0,0 +1,67 @@
+# Envoy deliveries
+
+Read this when a delivery field is unclear, or when a publish did not reach a session you expected.
+
+## A rendered delivery
+
+Envoy renders an annotated delivery before its source summary and complete payload:
+
+```text
+envoy:
+  to: you (ses_example_recipient)
+  from: 01a0bbbb-cccc-7ddd-eeee-0123456789ab (Reviewer)
+  at: "2026-09-07T04:41:12Z"
+  delivered: "2026-09-07T04:41:13Z"
+  id: agent-message-2
+  by: "2026-09-07T05:00:00Z"
+  urgency: high
+  expects_reply: required
+  re: agent-message-1
+  supersedes: agent-message-0
+  reply_with:
+    tool: envoy_send
+    args:
+      session_id: 01a0bbbb-cccc-7ddd-eeee-0123456789ab
+      in_reply_to: agent-message-2
+      message: ...
+  reply_role:
+    tool: envoy_publish
+    args:
+      topic: notifications.role.legion-reviewer
+      message: ...
+  summary: Deployment needs confirmation.
+  message: "Confirm the listener health check passed.\n\nThen publish the release."
+  note: body names session 01a0cccc-dddd-7eee-ffff-0123456789ab; the sender is 01a0bbbb-cccc-7ddd-eeee-0123456789ab
+```
+
+- `to`: the local inbox that receives this delivery.
+- `from`: the sending session's self-asserted id, with its session title in parentheses when the envelope carries one. Attribution and a direct-reply target, not an authenticated identity.
+- `at`: when the server that accepted the delivery took it, by that server's clock: the Envoy listener the sender sent through for a session's message or a webhook event, Dispatch's server for a Dispatch event. The sending session sets no time of its own; its machine's clock counts only where that listener runs on the same machine. It is not the present time: a delivery read late carries an old `at`.
+- `delivered`: when this session got the delivery, by this machine's clock. An Oh My Pi session shows it in every model request, beside `at`, or beside `published_at` on a notice that names a message the session could not be shown. A session the host moves to shows when it got the delivery there, which can be later than another session got it. A session that got the delivery before its process restarted can show an estimate of that time, taken from its transcript, never later than the delivery.
+- `waited`: present when `delivered` is 15 minutes or more after the send time, less any clock difference `clocks` states: how long the delivery waited, in words. An old send time on a late delivery says the delivery waited, not that a clock is wrong.
+- `clocks`: present when this machine's clock runs 15 minutes or more ahead of or behind the Envoy listener's, read from the listener's replies, or when `delivered` is 15 minutes or more before the send time less that difference: which way the clocks differ, and by how much. Only this machine's clock and the listener's are measured, so a send time still after the delivery once the measured difference is taken off says the sending server's own clock runs ahead of the listener's. A difference under 15 minutes is not shown and stays in `waited`.
+- `id`: the delivery id; pass it as `in_reply_to` when you reply.
+- `by`: the expiry deadline, when the sender set one.
+- `urgency`: how soon the sender asks you to act: `low`, `med`, `high` or `blocking`. It is for you to read only: it does not change when a delivery reaches you, or its place among others.
+- `expects_reply`: `none`, `optional` or `required`.
+- `re`: the delivery this one replies to. A Dispatch frame names it as a `dispatch://` ref: the ask (`dispatch://KEY/ask/<id>`, or `dispatch://PROJECT/artifact/<slug>/ask/<id>` for a document ask) or the message (`dispatch://KEY/message/<id>`), never the quoted text. On an ask, `dispatch.question` holds the start of the question's text; `dispatch read` gives the whole.
+- `supersedes`: an earlier delivery this one replaces; act on this one in its place.
+- `reply_with`: the direct-reply call to the sender. On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes.
+- `reply_role`: the role-publish reply call, when the sender holds a role.
+- `summary`: the one-line source summary.
+- `message`: the complete payload; it can hold several paragraphs.
+- `note`: the payload names another session; never use that quoted id as the recipient.
+- `unrecognised`: present when the payload failed validation or came from an unknown source. It names what failed, not every unknown key.
+
+## Who receives a publish
+
+It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
+
+- An Oh My Pi or Claude Code session takes its messages from a durable consumer the listener keeps for it on Envoy's stream and relays to it in order, acknowledging each one only once the session wrote it. So every message the stream keeps — your inbox, and each topic you follow with `envoy_subscribe` — reaches you once, whoever sent it: your own publish included, and a subagent's publish to a topic its parent follows. One published while you were restarting, disconnected or not running reaches you when you are back, up to 72 hours later. A session does not take its messages from a NATS subscription of its own; `packages/envoy/AGENTS.md`, "Session consumers", is the rule.
+- A team or other ad-hoc topic is the exception: the stream keeps none, so such a topic reaches only the sessions connected and subscribed when it is published, and nothing recovers it. The listener also forwards the message to the inbox of every other session registered on the topic with `envoy_subscribe`, and the stream keeps that copy, so a session that registered it gets it once after a restart too. What a team topic you subscribed to without registering carried meanwhile is gone.
+- A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session. The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart. A role message no live holder can take is kept for the session that claims the role next, which is handed it once, within one hour of the keep.
+- A session whose plugin, or whose listener, is of an earlier release falls back to the core path while the rollout lasts (dispatch://INFRA-771 removes it): there it receives live on its own NATS subscriptions, and recovers what the stream stored for it itself, marked as published while its connection was down. It does not recover a role message that way.
+
+## Listener API errors
+
+When you call the listener's `/v1` API directly, every error response is JSON, and when a field is at fault, `expected` names it: fix that field and retry.

package/skills/envoy/references/legion.md

@@ -0,0 +1,14 @@
+# Envoy in a Legion pane
+
+Read this in a Legion pane before you touch a role claim, or when a Legion role message fails.
+
+- The Legion plugin claims your assigned role at session start through a daemon-minted role token. Never call `envoy_role_set` and never subscribe to your role topic yourself, because the claim is already made (`packages/pi-shared/src/legion-claim-core.ts`).
+- Never build a role token from an issue number or title: only the daemon maps tokens to issues.
+- A Legion claim is last-claim-wins. It survives parking and worker re-creation, and stays through the issue's linger after close (the deployment's `linger_hours`).
+- `no_holder`, `holder_lapsed`, `delivery_failed` and `receipt_timeout` on a Legion role are the daemon's liveness signals. Never add a second subscriber or retry by hand: the daemon revives or recreates the worker and re-delivers, or relaunches the root process, which gets a `catch-up` notice of its tree and reads each issue's handoffs on its Dispatch issue (`dispatch handoff-read`).
+  - `no_holder`: no session holds the role's claim. Only the reaper releases a claim, once its holder is `gone`; a Legion role whose agent process exits is `gone` at once, so its successor's soft claim takes the role without waiting out the live window.
+  - `holder_lapsed`: a session holds the claim but has not registered within the live window, so the listener refused the publish `404` and forwarded nothing. The error names the holder, its `holder_state` and its `last_seen`, and says `claim_released: false`. An `unresponsive` holder is not dead: it keeps the role, nothing replaces it, and the daemon holds the packet and publishes it again.
+  - `delivery_failed`: the message is not known to have reached the holder: the holder lookup failed, the holder's session could not be reached, the publish errored, or the stream did not store the forward. A role message published straight onto NATS gives it for an unresponsive holder too. In the stream case the holder can have seen the message live, and its dedupe drops a re-sent copy. It releases no claim.
+  - `receipt_timeout`: the listener forwarded the message to a live holder and no receipt arrived in time. The error names the holder. Its payload keeps `original_topic`, `event_id`, `payload` and the original `dedupe_key`, so the daemon can re-send it and the receiver's dedupe drops a copy that did arrive.
+- A role message forwarded to you is kept on your inbox in the stream, which your own durable consumer reads, so your session gets it once, also after the pane restarts or reconnects.
+- Never forward these failure payloads to an architect, because the daemon already acts on them.

package/skills/envoy/references/roles.md

@@ -0,0 +1,12 @@
+# How a role claim lives
+
+Read this when a role you held is gone after a resume, fork or restart, when `envoy_role_set` is refused, or when Envoy keeps a role publish because no live session holds the role.
+
+- A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in the session transcript, also after the reaper removed the old session's row (the reaper removes a row only once that session is `gone`: past the gone horizon, `ENVOY_SESSION_GONE_HORIZON`, 1h by default).
+- `/fork`, `/branch`, `/handoff` and any other switch that carries the transcript read the role the previous session id held and move it to the new id while the new session starts. `/new` and `/resume` install an unrelated transcript and carry nothing.
+- A holder that has not registered for longer than the live window (`ENVOY_SESSION_LIVE_WINDOW`, 5m by default) reads `unresponsive`, and keeps its role: a role publish to it is refused `404 holder_lapsed`, which names the holder, its `holder_state`, its `last_seen` and `claim_released: false`, and nothing is forwarded and nothing kept. An unresponsive holder is not dead, so hold the message and publish it again later, start no replacement for that session, and take nothing from it. Only the role-claim reaper releases a claim, once the holder is `gone`; from then Envoy keeps each role publish for the session that claims the role next, and the answer says it was kept, until that transcript resumes or another session claims the role. A client that stops cleanly deregisters its own session and sends its client instance id, and the listener removes the registration only when the registration carries the same id or none, so a departing client never removes a registration another process made under the same session id.
+- A role message the listener forwarded to your session while you held the role is kept on your inbox in the stream, which your own durable consumer reads, so your session gets it once after a resume or a reconnect within 72 hours, also when the role moved to another session in the meantime.
+- An automatic reclaim never steals. It is a soft claim, which the listener grants when the role is unheld, when its holder is not `live` — `gone`, or `unresponsive` past the live window, which is how a relaunched Legion role recovers it — and when its holder is the id this session continues (a fork's parent) and that predecessor is this client instance's: the predecessor is not `live`, or its live registration carries this instance's own id, or one of the two sides carries no instance id. A client instance is one Oh My Pi Envoy extension instance, or one Claude Code channel-server process; each mints its id when it starts. Any other `live` session keeps the role — the parent of a `/fork` whose role moved to the child, a second process on the same transcript, a named predecessor another client instance still runs — and the listener refuses atomically, naming that holder, while the resumed session logs a warning and holds nothing.
+- A refusal does not stop the session. The session keeps running, and it stays registered, but without the role. It does not claim again at each heartbeat. The Oh My Pi plugin takes the role at its next session event, once the holder is no longer live. The Claude Code channel takes the role at an explicit claim. Use `envoy_role_get` to read who holds the role now.
+- Only an explicit `envoy_role_set` is last-claim-wins. Running it again for a role this session already holds is harmless.
+- If another plugin made subscriptions that depend on your current role, `envoy_role_set` to a different role is refused, and the refusal names those subscriptions. `envoy_unsubscribe` keeps those subscriptions and lists them as kept.

package/skills/envoy/references/sources.md

@@ -0,0 +1,41 @@
+# Slack, Ghost Wispr and WhatsApp topics
+
+Read this when you subscribe to one of these sources or test its routing.
+
+## Slack
+
+- Use the real team id (`T...`), never a workspace slug: the topic carries the id, so a slug receives nothing.
+- Channel topics: `notifications.slack.<team>.<channel>.message` or `.mention`. One thread: `notifications.slack.<team>.<channel>.thread.<ts>.>`, with the dot in the thread timestamp written `_`.
+- A delivery has a one-line prose `summary` and a structured `message`. The payload records `subtype` for edits, deletes and bot messages, `thread_ts` for replies, and `bot_id` and `bot_name` when a bot sent it.
+- Reply in a thread with `slack_post`; its tool description gives the arguments and refusals.
+
+```text
+envoy_subscribe(["notifications.slack.T01234567.C01234567.thread.1_000.>"])
+```
+
+## Ghost Wispr
+
+Topics are `notifications.ghostwispr.<session>.<kind>`, where `kind` is `session.started`, `session.ended` or `summary.ready`. The summary is prose and the payload structured; A `summary.ready` payload carries `status`, `summary` (capped; `body_truncated` when cut), `summary_preset`, `timestamp` and `version`.
+
+```text
+envoy_subscribe(["notifications.ghostwispr.session-example.summary.ready"])
+```
+
+## WhatsApp
+
+Topics are `notifications.whatsapp.<phone>.<jid>.message` or `.status`. A JID contains dots, which become extra NATS tokens, so match a chat with `>`, never `*`.
+
+```text
+envoy_subscribe(["notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>"])
+```
+
+To test Envoy routing without real WhatsApp ingestion, subscribe as above, then publish a synthetic message to the same `.message` topic:
+
+```text
+envoy_publish(
+  topic="notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message",
+  message="Synthetic WhatsApp routing test"
+)
+```
+
+The subscribed session should receive it. An Oh My Pi or Claude Code session receives its own publish, so it can run both steps. Real WhatsApp delivery also needs the listener's MCP bridge configured with a `whatsapp` server (`packages/envoy/internal/mcpbridge`).

package/skills/outside-message/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: outside-message
+description: "Use before any text reaches a person outside the company: a comment on an issue or pull request of a repository the company does not own, an email, a chat message to another company, a release note, an enrollment reply, a bug report, a disclosure. Use it also before you open an ask that asks the operator to approve such text. Not for a message to the operator, to another agent, or inside the company's own organization."
+---
+
+# A message to someone outside the company
+
+The operator approves every message that leaves the company, and four steps come before you ask.
+The rules below are the operator's own, from the answers that set them; this skill is where they
+are written down.
+
+## The exclusions
+
+An exclusion exists only where the operator has stated it. Never infer one from the shape of a
+message.
+
+**A project the operator has excluded by name** goes out without approval. Only the operator's own
+answer names such a project, and your stream's brief is where that answer reaches you. With no such
+answer for the project in front of you, there is no exclusion.
+
+**A pull request to a project that has already enrolled**, with its description and its comments to
+that project's maintainers. The operator does not want to be asked for approval every time for an
+enrolled project, and ceremony around a pull request must not stop the work. The four steps still
+apply. The approval ask does not. The work does not wait for the pull request either: prepare and
+sign the changes locally, and send them when the work they belong to ends.
+
+What counts as enrolled is the enrolling project's own record, and its stream's brief says where
+that record is. Do not decide enrollment from a message's tone, or from a maintainer having replied
+to the company before.
+
+Everything else waits for the operator: a first contact with a project that has not enrolled, a bug
+report, a disclosure, and a reply to a maintainer who wrote first.
+
+## The four steps
+
+1. **Research the audience.** Read the repository's contributing guide, its issue and pull-request
+   templates, its code of conduct, and its last ten issues or pull requests. Read how the
+   maintainers write to each other. Search for what has already been discussed about your subject; a
+   question they answered last month, asked again, costs you the reader.
+2. **Write for that audience, in their conventions.** Use their template where they have one, their
+   terms, their level of detail. Run `skill://asd-ste100` and `skill://plain-words` over the text.
+   Neither removes AI writing tells; where your session has a pass for those, run it as well.
+3. **Follow their conventions in form as well as words.** A pull request on their repository uses
+   their pull-request template. An issue uses their issue template. A thread reply matches the
+   thread.
+4. **A fresh reviewer reads it and cuts.** Dispatch a subagent that has not seen the drafting, give
+   it the message and the research, and tell it to remove everything that is not needed to
+   understand the core message. A reviewer that only approves has not done step 4. A subagent with
+   no model of its own runs on yours. Where your session can give the reviewer a different model,
+   do: a reader of the same model as the writer is the weaker check, though no measurement here
+   separates the two.
+
+**Step 4 ends with a list of what it removed, and that list goes in the ask.** Measured on
+2026-10-30 over 18 drafts of three real messages: drafts written with this skill met the bar 9
+times in 9, drafts with no guidance 8 times in 9, so the first three steps changed almost nothing
+— the research teaches them. The step that changed the message was the cut, and it is the step
+agents skip: 2 of 9 with the skill and 3 of 9 without had no cut at all. Only the cut drafts lost
+a promise about a future release, and they lost half their length. An instruction alone did not
+make the cut happen, so the list is what proves it did: three lines naming what came out, or the
+sentence "the reviewer removed nothing", which is itself an answer.
+
+The form of the text is not in this skill. Where the stream that owns the relationship keeps its own
+rules for writing to maintainers — in its project's `AGENTS.md`, in its skills, or in its brief —
+those rules decide how the message reads, and some of them are owned by people through that
+repository's code owners. Read them before you draft, and send a change to the form there rather
+than into this file.
+
+This skill covers when approval is needed and what comes before the ask. The project's own rules
+cover how the text reads.
+
+## Then the ask
+
+**Put the full message text in the ask itself.** Not a link to a document holding it, not a summary
+of it, not "the draft is at …". The operator has to open another document to read the message in
+almost every one of these asks, and cannot judge the message from the ask.
+
+An ask for an outside message has, in this order:
+
+- who the reader is, and one line on what they already know about this;
+- **the message, in full, as it would be sent**;
+- **what the reviewer removed in step 4**, in three lines or fewer, or "the reviewer removed
+  nothing";
+- what changes if the answer is no.
+
+Link the research, not the message. An ask with no removal line has not had step 4, whatever it
+says.
+
+## Never write these
+
+Delete the empty verb phrases and say the literal thing instead. These shapes:
+
+| Never | Write instead |
+|---|---|
+| "to name the problem" | say the problem |
+| "land the change" | merge it, release it, deploy it — whichever it is |
+| "carry the finding to X" | tell X, send X, put it on the issue |
+| "this shows the gap" | the gap is … |
+| "that pays for itself" | it costs $X and returns $Y |
+
+The test: delete the verb phrase and ask what literally happens. If you cannot say what happens, you
+did not know, and the phrase hid that from both of you. Write what happens.
+
+The same rule runs over asks, specs, messages, commit bodies and pull-request descriptions, not only
+outside messages. `skill://plain-words` has the full list and the rewrites.
+
+## What this skill does not cover
+
+- Text written in a person's own name, which that person signs off.
+- A message to another agent or to the operator: write it plainly and send it; no approval step.
+- Posting a release the pipeline publishes from approved template text: the template was approved
+  once; the release needs no new ask unless its text changes.