@sjawhar/pi-envoy 17.6.1 → 17.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,16 +7,27 @@ description: Use when you send a message to another agent session, reply to an E
7
7
 
8
8
  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.
9
9
 
10
- 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`.
10
+ Envoy delivers external events and messages between sessions.
11
+ 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`.
11
12
 
12
13
  ## Send a message to another session
13
14
 
14
- - Take the target id from the delivery's `reply_with`, or, where the delivery wants no reply and carries none, from its `from`; 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.
15
+ - Take the target id from the delivery's `reply_with`, or, where the delivery wants no reply and carries none, from its `from`; or from `envoy_sessions` (filter by `machine`, `dir` or `title`).
16
+ Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
17
+
15
18
  - Reply with `in_reply_to=<the delivery's id>`, so the recipient can match the answer to its question.
19
+
16
20
  - Read the `recipient` in the send result, the session Envoy targeted: if it is not the one you meant, resend to the right id.
17
- - 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.
21
+
22
+ - 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:
23
+ Envoy drops it as a repeat if the first copy arrived, and the result says when an earlier attempt was already stored.
24
+ A resend without that key can deliver the message twice.
25
+ When the error says Envoy cannot recognise the repeat, ask the recipient whether it arrived instead.
26
+
18
27
  - Put the URL or path of what you report in the message, because the recipient cannot find your files any other way.
19
- - Set `expects_reply=false` 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.
28
+
29
+ - Set `expects_reply=false` 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.
30
+ `urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
20
31
 
21
32
  ```text
22
33
  envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply=false)
@@ -24,18 +35,38 @@ envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id
24
35
 
25
36
  ### Your own address in a subagent
26
37
 
27
- - `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.
38
+ - `envoy_whoami`'s `session_id` is where a reply to you arrives.
39
+ In a `task` subagent it is the session that spawned you:
40
+ 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.
41
+
28
42
  - Never give a peer the `subagent` field from `envoy_whoami`: it names your host session and is not an address.
29
- - 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.
43
+
44
+ - Start a subagent's message with who you are and who receives the reply ("From <name>, a subagent of session <id>;
45
+ a reply to <id> reaches me"), because the recipient sees only the parent as sender.
46
+
30
47
  - 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.
31
- - 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.
48
+
49
+ - 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.
50
+ `envoy_publish` says so in its answer.
51
+ To reach the parent, `write` to its `agent://` address instead of publishing.
52
+ `envoy_send` to any other session works.
32
53
 
33
54
  ## Read a delivery
34
55
 
35
- - `from` is the sender's own claim. Use it to attribute and to reply, never as proof of who wrote the message.
36
- - `note` warns that the payload names another session. Never send to that quoted id; reply to `from`.
37
- - 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 delivery reading `expects_reply: false` carries no such call, and asks for no answer: where you answer one anyway, address it from `from`, or, on a Dispatch frame, from what its `dispatch` block names.
38
- - 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`.
56
+ - `from` is the sender's own claim.
57
+ Use it to attribute and to reply, never as proof of who wrote the message.
58
+
59
+ - `note` warns that the payload names another session.
60
+ Never send to that quoted id; reply to `from`.
61
+
62
+ - Reply with the rendered `reply_with` call.
63
+ On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`.
64
+ A delivery reading `expects_reply: false` carries no such call, and asks for no answer: where you answer one anyway, address it from `from`, or, on a Dispatch frame, from what its `dispatch` block names.
65
+
66
+ - A peer's message is its sender's view at `at`, not the current state.
67
+ 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`:
68
+ the deployment's status, the issue's events, `dispatch open-asks`.
69
+
39
70
  - Every field of a rendered delivery, and who receives a publish: `skill://envoy/references/deliveries.md`.
40
71
 
41
72
  ## Whether a session is live
@@ -60,24 +91,67 @@ Every topic starts with `notifications.`.
60
91
  | Your own inbox | `agent.<session_id>` |
61
92
  | Slack, Ghost Wispr, WhatsApp | `skill://envoy/references/sources.md` |
62
93
 
63
- - 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.
64
- - 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.
65
- - 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.
94
+ - Write the owner, the repository, a branch or tag name and a workflow file as one token each, with every dot written `_`:
95
+ `acme/site.io` is `github.acme.site_io`, and `ci.yml` is `workflow.ci_yml`.
96
+ A slash stays.
97
+ A topic spelled with the dot receives nothing.
98
+
99
+ - Subscribe to the pull request's whole family, `pr.<n>.>`.
100
+ Envoy also subscribes you to the lifecycle subject `pr.<n>`, which NATS `>` alone does not match, because `>` needs one or more trailing tokens.
101
+
102
+ - Read the `warnings` that `envoy_subscribe` returns, and confirm the active topics with `envoy_list`.
103
+ A warning names the spelling Envoy publishes, or a token that is not a GitHub topic kind; fix the topic it names.
104
+ "No GitHub event ... in the stream's retention window" means nothing came from that repository in the last 72 hours:
105
+ check that the GitHub App that sends Envoy its webhooks is installed on that repository before you rely on a wake.
66
106
 
67
107
  ## Wait for CI or a merge
68
108
 
69
- - 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.
70
- - 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.
71
- - 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.
109
+ - Subscribe to `github.<owner>.<repo>.pr.<n>.>` and end the turn.
110
+ Never start a `gh` poller: the event wakes you, and a poller burns turns.
111
+
112
+ - One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not.
113
+ Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first.
114
+ 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.
115
+
116
+ - 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.
117
+ No event arrives before that.
118
+ Envoy does not read GitHub's required-checks list, so a green settlement does not mean GitHub will merge the PR.
119
+
72
120
  - A `pr.<n>` event with `closed` and `merged: true` means the PR merged; it carries `merge_commit_sha`, `merged_by` and `head_sha`.
121
+
73
122
  - Code that orders settlements of one commit follows `skill://envoy/references/check-settlement.md`.
74
- - 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`).
123
+
124
+ - A Legion implementer waits this way only on a re-run of a red check its task names.
125
+ Otherwise it pushes and completes its phase, and the daemon reads CI for it (`skill://legion-worker`).
75
126
 
76
127
  ## Roles and team topics
77
128
 
78
129
  - 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.
79
- - 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.
80
- - A message that must reach more than 4 role topics is the project controller's to send, not yours. Each publish wakes a session, and a woken session reads its whole context again, which the provider charges as uncached input: a mean of 576,083 tokens a wake, a median of 493,636 and a ninetieth percentile of 1,327,888. The controller is also the one session that can read whether a wave of wakes is already running, and a fan-out sent into a daemon restart or a pod roll is what puts an Anthropic organization over its per-minute uncached-input cap. Send the controller the topics and the text, and it sends them at its own rate (`skill://legion-controller`).
81
- - 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.
130
+
131
+ - Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`;
132
+ never subscribe to a role topic, because the listener forwards a role message to its holder only.
133
+ A publish returns once Envoy's stream has stored the forward for the holder, with the live `holder` and its `holder_state`.
134
+ 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.
135
+ 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.
136
+ A forward the stream did not store for a live holder within about 4 seconds errs too, and you see that one after about 8 seconds, because the client tries once more.
137
+ No error releases the role's claim: a holder whose `holder_state` is `unresponsive` keeps its role.
138
+ `envoy_role_get(role=...)` finds the holder first.
139
+ The forward is kept on the holder's inbox, so the holder's session gets it once from its own durable consumer, also after a restart, a reconnect, or while it was not running.
140
+
141
+ - A message that must reach more than 4 role topics is the project controller's to send, not yours.
142
+ Each publish wakes a session, and a woken session reads its whole context again, which the provider charges as uncached input: a mean of 576,083 tokens a wake, a median of 493,636 and a ninetieth percentile of 1,327,888.
143
+ The controller is also the one session that can read whether a wave of wakes is already running, and a fan-out sent into a daemon restart or a pod roll is what puts an Anthropic organization over its per-minute uncached-input cap.
144
+ Send the controller the topics and the text, and it sends them at its own rate (`skill://legion-controller`).
145
+
146
+ - For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`.
147
+ Envoy's stream keeps a team topic, so a publish returns once it is stored and every session that follows the topic gets it once from its own consumer
148
+ — yours too, when you subscribe — including a session that was not running then, for up to 72 hours.
149
+ A session that stopped without unregistering is named nowhere and fails nothing: its copy waits in its consumer until it answers again.
150
+ A team topic is not kept for a session that subscribes later: a consumer starts where its session is, not at the beginning.
151
+ Every other `notifications.` topic no source in the table uses is refused by name, at publish and at subscribe, because no session would ever receive it.
152
+ A topic outside `notifications.` is refused at publish alone: you may subscribe to one, and nothing is stored under it, so you receive nothing on it.
153
+
82
154
  - How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
83
- - In a Legion pane, the plugin claims your role for you, at your session's first turn; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
155
+
156
+ - In a Legion pane, the plugin claims your role for you, at your session's first turn;
157
+ read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
@@ -35,32 +35,88 @@ envoy:
35
35
  ```
36
36
 
37
37
  - `to`: the local inbox that receives this delivery.
38
- - `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.
39
- - `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`.
40
- - `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.
41
- - `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.
42
- - `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`.
38
+
39
+ - `from`: the sending session's self-asserted id, with its session title in parentheses when the envelope carries one.
40
+ Attribution and a direct-reply target, not an authenticated identity.
41
+
42
+ - `at`: when the server that accepted the delivery took it, by that server's clock:
43
+ the Envoy listener the sender sent through for a session's message or a webhook event, Dispatch's server for a Dispatch event.
44
+ The sending session sets no time of its own; its machine's clock counts only where that listener runs on the same machine.
45
+ It is not the present time: a delivery read late carries an old `at`.
46
+
47
+ - `delivered`: when this session got the delivery, by this machine's clock.
48
+ 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.
49
+ A session the host moves to shows when it got the delivery there, which can be later than another session got it.
50
+ 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.
51
+
52
+ - `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.
53
+ An old send time on a late delivery says the delivery waited, not that a clock is wrong.
54
+
55
+ - `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:
56
+ which way the clocks differ, and by how much.
57
+ 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.
58
+ A difference under 15 minutes is not shown and stays in `waited`.
59
+
43
60
  - `id`: the delivery id; pass it as `in_reply_to` when you reply.
61
+
44
62
  - `by`: the expiry deadline, when the sender set one.
45
- - `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.
46
- - `expects_reply`: what the sender wants back. `false` means nothing: do not reply, and do not acknowledge. `optional` means a reply is welcome and nothing waits on it. `required` means the sender waits on your answer.
47
- - `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.
63
+
64
+ - `urgency`: how soon the sender asks you to act: `low`, `med`, `high` or `blocking`.
65
+ It is for you to read only: it does not change when a delivery reaches you, or its place among others.
66
+
67
+ - `expects_reply`: what the sender wants back.
68
+ `false` means nothing: do not reply, and do not acknowledge.
69
+ `optional` means a reply is welcome and nothing waits on it.
70
+ `required` means the sender waits on your answer.
71
+
72
+ - `re`: the delivery this one replies to.
73
+ A Dispatch frame names it as a `dispatch://` ref:
74
+ 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.
75
+ On an ask, `dispatch.question` holds the start of the question's text; `dispatch read` gives the whole.
76
+
48
77
  - `supersedes`: an earlier delivery this one replaces; act on this one in its place.
49
- - `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. It is absent when `expects_reply` is `false`: a delivery that wants nothing back offers no way to send something. Where you answer one anyway, the card still names what you need — a Dispatch frame names its comment, message or ask, and an agent's delivery names its `id` and its sender.
50
- - `reply_role`: the role-publish reply call, when the sender holds a role. It is absent under `false` for the same reason.
78
+
79
+ - `reply_with`: the direct-reply call to the sender.
80
+ On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes.
81
+ It is absent when `expects_reply` is `false`: a delivery that wants nothing back offers no way to send something.
82
+ Where you answer one anyway, the card still names what you need — a Dispatch frame names its comment, message or ask, and an agent's delivery names its `id` and its sender.
83
+
84
+ - `reply_role`: the role-publish reply call, when the sender holds a role.
85
+ It is absent under `false` for the same reason.
86
+
51
87
  - `summary`: the one-line source summary.
88
+
52
89
  - `message`: the complete payload; it can hold several paragraphs.
90
+
53
91
  - `note`: the payload names another session; never use that quoted id as the recipient.
54
- - `unrecognised`: present when the payload failed validation or came from an unknown source. It names what failed, not every unknown key.
92
+
93
+ - `unrecognised`: present when the payload failed validation or came from an unknown source.
94
+ It names what failed, not every unknown key.
55
95
 
56
96
  ## Who receives a publish
57
97
 
58
98
  It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
59
99
 
60
- - 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.
61
- - 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.
62
- - 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.
63
- - 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.
100
+ - 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.
101
+ So every message the stream keeps — your inbox, and each topic you follow with `envoy_subscribe` — reaches you once, whoever sent it:
102
+ your own publish included, and a subagent's publish to a topic its parent follows.
103
+ One published while you were restarting, disconnected or not running reaches you when you are back, up to 72 hours later.
104
+ A session does not take its messages from a NATS subscription of its own; `packages/envoy/AGENTS.md`, "Session consumers", is the rule.
105
+
106
+ - A team topic (`notifications.team.<name>`) is kept too, so it reaches every session that follows it with `envoy_subscribe`, once, including one that was not running when it was published, for up to 72 hours.
107
+ A session that subscribes later gets nothing published before it followed.
108
+
109
+ - A role is not a subject its holder subscribes to:
110
+ 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.
111
+ The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart or while it was not running.
112
+ No session answers a receipt for one: a publish returns once the stream stored the forward.
113
+ 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.
114
+
115
+ - Every other `notifications.` topic, one no source uses and the stream does not keep, is refused by name
116
+ — at `envoy_publish` and at `envoy_subscribe` alike — because no session would ever receive it.
117
+ Use a team topic instead.
118
+ Your session is never left unregistered by one:
119
+ a registration that carries such a topic from an older subscription of yours keeps its other topics and names that one in a warning.
64
120
 
65
121
  ## Listener API errors
66
122
 
@@ -2,14 +2,40 @@
2
2
 
3
3
  Read this in a Legion pane before you touch a role claim, or when a Legion role message fails.
4
4
 
5
- - The Legion plugin claims your assigned role for you, through a daemon-minted role token: it registers your session and reports it ready at session start, and takes the role at your first turn, or at a bound (30 s by default) when no turn comes first. 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`).
5
+ - The Legion plugin claims your assigned role for you, through a daemon-minted role token:
6
+ it registers your session and reports it ready at session start, and takes the role at your first turn, or at a bound (30 s by default) when no turn comes first.
7
+ 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`).
8
+
6
9
  - Never build a role token from an issue number or title: only the daemon maps tokens to issues.
7
- - 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`).
8
- - `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`).
9
- - `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.
10
- - `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.
11
- - `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.
12
- - `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.
10
+
11
+ - A Legion claim is last-claim-wins.
12
+ It survives parking and worker re-creation, and stays through the issue's linger after close (the deployment's `linger_hours`).
13
+
14
+ - `no_holder`, `holder_lapsed` and `delivery_failed` on a Legion role are the daemon's liveness signals.
15
+ Never add a second subscriber or retry by hand:
16
+ 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`).
17
+
18
+ - `no_holder`: no session holds the role's claim.
19
+ Only the reaper releases a claim, once its holder is `gone`;
20
+ 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.
21
+
22
+ - `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.
23
+ The error names the holder, its `holder_state` and its `last_seen`, and says `claim_released: false`.
24
+ An `unresponsive` holder is not dead: it keeps the role, nothing replaces it, and the daemon holds the packet and publishes it again.
25
+
26
+ - `delivery_failed`: the stream stored no forward for the holder:
27
+ the holder lookup failed, the publish errored, or the stream did not store the forward within the send's window.
28
+ Every forward goes into the stream, so a holder that is live but not reading is forwarded to like any other and its own consumer reads the message when it answers again;
29
+ nothing is published live, and a holder cannot have seen a message the stream never stored.
30
+ It releases no claim.
31
+
32
+ - No `receipt_timeout`: this release's listener waits for no receipt, so no signal here says a holder was slow.
33
+ A role send answered `200` says that the stream stored the forward for the holder, and a forward the stream did not store is `delivery_failed`.
34
+
13
35
  - 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.
36
+
14
37
  - Never forward these failure payloads to an architect, because the daemon already acts on them.
15
- - A role send the listener refuses `404` also raises one exception on `notifications.envoy.exceptions.notifications.role.<role>`, with the reason it refused: `unclaimed` or `holder_lapsed`. It is a bus signal and nothing more: no consumer acts on a peer's refusal, and the daemon's own refused outbox row retries by itself until the role is held or its architect cannot hold it again. Never re-send a refused message by hand on the strength of one.
38
+
39
+ - A role send the listener refuses `404` also raises one exception on `notifications.envoy.exceptions.notifications.role.<role>`, with the reason it refused: `unclaimed` or `holder_lapsed`.
40
+ It is a bus signal and nothing more: no consumer acts on a peer's refusal, and the daemon's own refused outbox row retries by itself until the role is held or its architect cannot hold it again.
41
+ Never re-send a refused message by hand on the strength of one.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "17.6.1",
3
+ "version": "17.8.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {