@sjawhar/opencode-legion-envoy 1.51.0 → 1.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -154,10 +154,51 @@ Architects create newly tracked child work with:
 ```ts
 dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3, assignee?: string })
 ```
-`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. Set `priority` on creation only when the human's intent makes the bucket clear; otherwise priority remains the human's decision. Set `assignee` (a GitHub login on the sign-in allowlist) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It returns
+`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. `priority` is yours on creation too — see [Priority is yours to set](#priority-is-yours-to-set). Set `assignee` (a GitHub login on the sign-in allowlist) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It returns
 `details` `{ issue }`; creating an issue does not subscribe you to it (see [Following](#following)). Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is supplied,
 follow [Writing a spec](#writing-a-spec).
 
+## Claim the issue before you work it
+
+Two sessions once spent a night implementing the same issue, because nothing on it said who was
+on it (Sami, 2026-09-24, verbatim: "It seems like we need a better way of tracking what's already
+in progress"). So before you start implementing an issue, claim it:
+
+```ts
+dispatch_claim({ issue: "LEGION-234" })                  // I am implementing this
+dispatch_claim({ issue: "LEGION-234", release: true })   // I have stopped; it is free
+```
+
+A claim records **your** session — the one making the call, never another — and shows on every
+read of the issue: the dashboard header, the issue list and board, `dispatch_read` (a
+`Claimed by:` line) and `dispatch_issues` (a claim on the row). `dispatch_issues` plus the
+dashboard's **Unclaimed** filter is how you find work nobody is on.
+
+- **`409 ISSUE_CLAIMED` means someone else holds this issue.** When it is another session, the
+  refusal names it and says it is still running: do not work the issue in parallel — message
+  that session (its id is in the message; `envoy_send` reaches it) or pick up something else,
+  and tell the human if you believe the work should be yours. When a **human** holds it, the
+  refusal names the person and says nothing about a session running, because there is none to
+  message: ask them on the issue (`dispatch_message`) instead, and never assume their claim has
+  lapsed — only a human releases or forces a human's claim.
+- **`409 CLAIM_CONTENDED` means the issue changed hands twice while your call ran**, so nothing
+  was applied and nobody's liveness was checked. Read the issue and decide again; it is not a
+  refusal by a live holder.
+- **A claim whose session has ended is yours to take.** If the Envoy listener no longer lists
+  the holder, your claim simply succeeds; the takeover is recorded on the issue and the session
+  that lost it is told.
+- **Release it when you stop** — finished, handing over, or moving to something else. A claim is
+  released by its holder or any human — and by any agent once the holder's session is no longer
+  running, the same rule that lets you take it. Closing the issue releases it for you.
+- A claim is intent to implement, not contact: reading the issue, commenting, asking, or gating
+  its pull request claims nothing, so a coordinator never collides with an implementer.
+
+**Claiming and moving the status are two separate actions, and you do both.** A claim says which
+session is on the work; the status says where the work has got to, and humans use it to track
+that too (Sami, 2026-09-24, verbatim: "Keep them separate — Separate because humans might be
+using them to keep track of work"). So when you start: `dispatch_claim({ issue })` **and**
+`dispatch_issue_update({ issue, status: "in_progress" })`.
+
 ## Issue status is yours to move
 
 The issue's status is how a human sees delivery without asking a session. Outside Legion (where
@@ -167,16 +208,19 @@ production-like surface, `needs_review` when its pull request is open and waitin
 queue, `done` when the change has been driven in production (a merge is not `done`). Move child
 issues you own as well as the root. An issue left at `triage` while work is underway is a defect:
 Sami, 2026-09-15, on the roadmap he could not read — "I'm not even sure what their development
-status is." Waiting for the deploy lane is not a status and is never announced. Priority stays the
-human's: set it on creation only when their intent is clear, and change it only on their word.
+status is." Waiting for the deploy lane is not a status and is never announced.
 
 ```ts
-// PATCH /api/v1/issues/{key} — status, title, labels, external_links (merged by URL), route, parent
+// PATCH /api/v1/issues/{key} — status, title, labels, priority, external_links (merged by URL), route, parent
 dispatch_issue_update({ issue: "AGENTC-175", status: "testing" })
+dispatch_issue_update({ issue: "AGENTC-175", priority: 1 }) // 0–3; see Priority is yours to set
 dispatch_issue_update({ issue: "AGENTC-175", external_links: ["https://github.com/owner/repo/pull/7"] })
 dispatch_issue_update({ issue: "AGENTC-175", parent: "AGENTC-170" }) // same-project key; "" clears the parent
 ```
 
+The two clears differ: `priority` clears with `null`, while `parent` and `route` clear with `""`.
+Guessing the other one is a refusal either way.
+
 Link the pull request that delivers the issue in `external_links` when you open it; the issue page
 renders its state and checks from that link. The call is authenticated with the same bearer as every
 other `dispatch_*` tool: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
@@ -185,6 +229,18 @@ the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/o
 A write to an issue still in `triage` answers once with `… is still in triage …`; move the status
 when work has started.
 
+## Priority is yours to set
+
+Priority is the coarse bucket a backlog is read by: `0` is P0, the highest, through `3`, P3, the
+lowest, and `null` clears it. Sami ruled on 2026-09-24, answering "may agents set issue priority
+(P0–P3), or only propose it for you?" on `dispatch://LEGION/artifact/issue-status-conventions-md`:
+**"Agents may set"**. So set it — on creation, and on a grooming pass over issues that have none —
+and say what you set and why; he overrides anything he disagrees with from the dashboard. A closed
+issue takes only `rank`, `components`, and a reopening `status` (any status but `done`);
+everything else, `priority` included, waits for the reopen (`409 ISSUE_CLOSED`). So reopen it
+first, then set the priority — the two cannot go in one call. `rank` itself is not a tool field:
+reorder it the way [Issue reads](#your-owner) describes, through `PATCH /api/v1/issues/{key}`.
+
 ## Search first
 
 Before you create an issue or start a design document, search: