@sjawhar/pi-envoy 16.0.0 → 16.2.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.
@@ -8,16 +8,16 @@ description: "Use before your first dispatch command in a session: a message, co
8
8
  Dispatch is a record for the people who decide, never a log of your work.
9
9
 
10
10
  - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
11
- - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
11
+ - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`); give object and list fields as JSON.
12
12
  - Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
13
13
 
14
14
  ## Asks and ask blocks
15
15
 
16
- - A design question a document records is an ask block (a decision block) at the end of its section, at each phase:
16
+ - A design question a document records is an ask block (a decision block) at the end of its section:
17
17
 
18
18
  ```md
19
19
  :::ask{urgency="med"}
20
- Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation: the option and its reason.
20
+ Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation and its reason.
21
21
 
22
22
  - Option one: what it costs.
23
23
  - Option two: what it costs.
@@ -27,7 +27,7 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
27
27
  - In Legion, fix a clear defect in code your tree uses, hand others to the controller, and ask about decisions (`skill://legion-worker/references/findings.md`).
28
28
  - An open ask is the request; never repeat it per message.
29
29
  - Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
30
- - Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` for a note needing nothing. An approval request a newer version moved needs `request-approval` again.
30
+ - 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.
31
31
  - When an answer's option and text disagree, the text wins.
32
32
  - 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.
33
33
  - An ask reaches the issue's assignee; if none, name who answers.
@@ -41,9 +41,9 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
41
41
 
42
42
  ## Issue status is yours to move
43
43
 
44
- 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. An issue with the `legion` label, or under one: never write its status with `dispatch` or route it, and claim it only as a role of its tree, even when its claim reads `· not running`. An outside claim can take the tree out of the workflow. A status write is set back or stands.
44
+ 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, even when its claim reads `· not running`: an outside claim can take the tree out of the workflow. A status write is set back or stands.
45
45
 
46
- 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 event Dispatch marks quiet.
46
+ 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.
47
47
 
48
48
  ## Close what you opened
49
49
 
@@ -79,7 +79,7 @@ dispatch://PROJECT/artifact/<slug>/ask/<id>
79
79
  dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
80
80
  ```
81
81
 
82
- 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, from `dispatch read`'s `Ask id:` or the page URL: the command takes a prefix, a person's link does not.
82
+ 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.
83
83
 
84
84
  ## Setup and the HTTP API
85
85
 
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: dispatch-writing-specs
3
- description: "Use in a session with Dispatch before you write or change a spec, and before an ask, comment or message a person reads. It replaces superpowers' brainstorming there."
3
+ 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."
4
4
  ---
5
5
 
6
6
  # Writing specs
7
7
 
8
8
  ## The aim
9
9
 
10
- Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec (`skill://legion-worker`).
10
+ Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes none (`skill://legion-worker`).
11
11
 
12
12
  ## The outline
13
13
 
@@ -18,12 +18,12 @@ Part | Content
18
18
  `Summary` | The change in the reader's own terms, at most 100 words
19
19
  `Problem` | What goes wrong, for whom, with counts
20
20
  `Goals and non-goals` | What is in and out of scope
21
- `Requirements` | `**R1.**` on, each naming its source (`From:`)
21
+ `Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
22
+ `Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run`, `when`, `negative_control`
22
23
  `Design` | How it meets them; a value and its reason for each limit, size and time
23
24
  `Decisions` | One line: `The decisions are in dispatch://KEY/artifact/decisions-md.`
24
- `Acceptance` | `**A1.**` on, each naming the requirements it tests
25
25
 
26
- Another agent can build and check the work from the spec alone. A small change gets a few sentences per part, no matrix; split a large design into child issues.
26
+ `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.
27
27
 
28
28
  ## Rules for the text
29
29
 
@@ -33,7 +33,7 @@ For each spec, ask, comment and message:
33
33
  - Write about the current design, never the person or how people reached it, and never quote people or upload their words.
34
34
  - Link each source where the person wrote it, each id whole. With no link, state the design.
35
35
  - In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
36
- - A sentence that cites a gate passing (test, review, check, proof) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
36
+ - 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."
37
37
  - Name your session only if a reader must reach it.
38
38
  - Keep only text that helps a reader understand, decide, build, check.
39
39
  - Explain each name or term a new reader may not know, and what each issue you name does for them.
@@ -68,9 +68,9 @@ At your next edit, rewrite a spec outside the outline whole in one version, movi
68
68
 
69
69
  ## Approval
70
70
 
71
- - Request approval once: each ask block answered or waived, each claim checked, this version unapproved. Unbuilt acceptance checks never delay it.
72
- - After approval, version only a change to scope, acceptance, 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.
71
+ - 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.
72
+ - 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.
73
73
 
74
74
  ## The plan
75
75
 
76
- Write the plan with `writing-plans` as the issue's `plan.md`, not a repository file.
76
+ 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`.
@@ -66,7 +66,7 @@ Every topic starts with `notifications.`.
66
66
  ## Roles and team topics
67
67
 
68
68
  - 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.
69
- - 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`. An unheld role returns an error, and so does a holder that did not confirm the message within about 4 seconds; that error names the holder, and you see it after about 8 seconds, because the client tries once more. `envoy_role_get(role=...)` finds the holder first. The stream keeps the forward on the holder's inbox, so the holder's session gets it once from its own durable consumer, also after a restart or a reconnect.
69
+ - 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`. When nobody holds the role, or its holder's claim has lapsed, Envoy keeps the message for the session that claims the role next. The answer then says the message was kept, and that session is handed it once, within one hour of the keep. A holder that did not confirm the message within about 4 seconds returns an error that names the holder, and you see it after about 8 seconds, because the client tries once more. `envoy_role_get(role=...)` finds the holder first. The stream keeps the forward on the holder's inbox, so the holder's session gets it once from its own durable consumer, also after a restart or a reconnect.
70
70
  - 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. A session that stopped without unregistering stays registered for up to 5 minutes and is named in that time; 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.
71
71
  - How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
72
72
  - 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.
@@ -59,7 +59,7 @@ It depends on where a session takes its deliveries, not on whether the topic is
59
59
 
60
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
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.
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
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.
64
64
 
65
65
  ## Listener API errors
@@ -1,10 +1,10 @@
1
1
  # How a role claim lives
2
2
 
3
- Read this when a role you held is gone after a resume, fork or restart, when `envoy_role_set` is refused, or when a role publish returns `no holder`.
3
+ 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.
4
4
 
5
5
  - A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in the session transcript, also after the listener removed the dead session's old row (a session's registration lapses 5 minutes after its last heartbeat).
6
6
  - `/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.
7
- - A process that dies and is never resumed stops being a live holder. Until its registration lapses, role publishes return an error that names the holder and says it did not confirm the message (`receipt_timeout`). Once it lapses, they return `no holder`, 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. The listener then 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.
7
+ - A process that dies and is never resumed stops being a live holder. Until its registration lapses, role publishes return an error that names the holder and says it did not confirm the message (`receipt_timeout`). Once it lapses, Envoy keeps each role message for the session that claims the role next, and the publish's 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. The listener then 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.
8
8
  - 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.
9
9
  - An automatic reclaim never steals. It is a soft claim. The listener grants it when the role is unheld, and when its holder is no longer live. It also grants it when the holder is the session this claim continues, in three cases: that predecessor has no live registration, or its live registration carries this client 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. A predecessor that another client instance still runs keeps the role. The listener then refuses the claim and names that holder.
10
10
  - 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, after the holder is gone. The Claude Code channel takes the role at an explicit claim. Use `envoy_role_get` to read who holds the role now.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.0.0",
3
+ "version": "16.2.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {
@@ -16,7 +16,7 @@
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",
19
- "url": "https://github.com/sjawhar/legion"
19
+ "url": "https://github.com/cybermonklabs/legion"
20
20
  },
21
21
  "files": [
22
22
  "dist",