@sjawhar/opencode-legion-envoy 3.13.0 → 3.14.0

package/skills/dispatch/references/api.md

@@ -0,0 +1,28 @@
+# Authentication and the HTTP API
+
+`skill://dispatch` sends you here when you set up a Dispatch token, or need a route the tools do
+not cover.
+
+## Agent authentication
+
+Use a personal Dispatch token: a human mints it in Dispatch **Settings → Agent tokens** and supplies
+it to the agent through `dispatch.token` in `~/.config/opencode/envoy.json` or `DISPATCH_TOKEN`.
+The server records the minting human as the owner of that session's writes. `DISPATCH_AGENT_TOKEN`
+is the shared devbox fallback; do not configure it for an individual agent.
+
+The deployed Dispatch server's browser origin is configured separately with
+`DISPATCH_SERVER_URL` in the deployment `compose/.env`. Do not change an
+agent's `envoy.json` to set the GitHub OAuth callback origin: the value must
+be the exact URL humans type in their browser, and the GitHub App callback is
+`<DISPATCH_SERVER_URL>/auth/callback`.
+
+### Finding a route
+
+The tools cover the everyday surface. For anything else, ask the server: `GET /api/v1` (no
+credential) returns every route as `{method, path, auth, description}` sorted by path — `auth`
+is `public`, `any` (a human or a bearer), `human` (a bearer gets `403 HUMAN_ONLY`), or `bearer`.
+A path Dispatch does not serve under `/api` or `/v1` answers
+`404 {"code":"NOT_FOUND","error":"no route for GET /v1/issues","hint":"GET /api/v1 lists every
+route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
+`/api/v1` error body carries a `code`; branch on the code, never on the text.
+

package/skills/dispatch/references/asks.md

@@ -0,0 +1,109 @@
+# Asks after they open: who answers, editing, resolving, replying, and following
+
+`skill://dispatch` sends you here once you are asking: to find who answers an ask, hand a human a
+to-do, edit or retract an ask, answer a clarification, say whose turn it is, or follow or leave its
+thread. Whether to ask at all, and how to write the question, is "Before you ask" in
+`skill://dispatch`.
+
+## Who answers an ask
+
+An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with:
+```ts
+dispatch_whoami({})
+```
+It returns `details` `{ session, owner, service }`: `owner` is the lowercase login of the human whose personal token you run under, or `null` under the shared token or a verified service token, in which case `service` is that token's subject (`system:serviceaccount:<namespace>:<name>`, `null` otherwise) and every write you make is rendered `(as <namespace>/<name>)` — the namespace is kept because every namespace has a `default` service account, and a subject that is not a Kubernetes one is shown whole. An issue you create without `assignee` goes to your owner; with no owner it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<login>"}`; any authenticated caller may reassign, and an unlisted login is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
+
+## Handing a human a to-do, editing, resolving, and replying
+
+A to-do handed to a human is an ordinary question: phrase the to-do as the question and give it
+the options that name its outcomes, in the human's words - there is no fixed vocabulary and the
+server treats no label specially. If an outcome needs a reason, say so in that option's
+description, and the human's free-text answer carries it:
+```ts
+dispatch_ask({ issue: "DSP-42",
+  question: "Run the production deploy for #19125?",
+  options: [{ label: "Deployed" }, { label: "Blocked", description: "Say what is missing." }] })
+```
+
+Correct or refine an open ask in place instead of opening a second question:
+```ts
+dispatch_edit_ask({
+  ask,
+  question?,
+  options?: { label, description? }[],
+  multiple?,
+  urgency?,
+})
+```
+At least one field besides `ask` is required. Use this only while the same decision remains open: it keeps the prior text in the event
+log and invalidates any answer draft against the prior `edited_at` revision, so the human sees the new wording and explicitly reconfirms.
+An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
+
+An ask that lives as an `ask` block in a document keeps its question and options in the block, and `dispatch_edit_ask` writes the
+block along with the row, so the edit stands and the document reads the same. It changes only the fields you name: pass `urgency`
+alone and the question's own wording, formatting, links and comment anchors are untouched. Pass `question` or `options` and that part
+is rewritten, so anchors inside the text you replaced move as they would for any document edit. Either way it is a document edit: it
+writes a new version, which on a spec awaiting approval closes the design gate until the new version is approved. Editing the block
+with `dispatch_doc_edit` works too and is the way to change anything else about it, including adding formatting to a question.
+Re-sending a field unchanged rewrites nothing, so retrying the whole ask is safe.
+Text the block cannot carry back unchanged is refused outright, naming the field and writing nothing - an option label containing
+`": "`, the separator between a label and its description, is one example of text that cannot survive the round trip. Blank lines separate paragraphs;
+a single newline is kept as a line break.
+
+An ask stays open until a human answers, unless its question no longer needs that answer. Retract a moot or superseded question, or
+self-resolve one after finding the answer:
+```ts
+dispatch_resolve_ask({
+  ask,
+  kind: "retracted",
+  reason: "A newer ask supersedes this question.",
+})
+```
+Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the reason because the question remains
+in its Conversation card and reply thread; a reason beginning `removed from the document in version` is refused, because that is how a
+retraction the document's own settlement wrote is recognised. Resolving a block ask records it in the block too, so it stays resolved
+however the document moves afterwards — while deleting the block from the document is the other way to close one, and putting the block
+back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
+resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
+`dispatch_comment` (mutually exclusive with `reply_to`).
+A review comment you opened has its own closer, `dispatch_resolve_comment` — see
+[Comments and suggestions](skill://dispatch/references/documents.md).
+
+A human answers or asks back from the same field; a question-shaped free-text answer is offered as a clarification first. A human
+reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for clarification, not
+an answer: the human did not understand the question or needs more before choosing. The ask now waits on you in their Inbox. Answer
+in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
+was the problem; either puts the ask back in front of them. Do not open a second ask.
+
+Every reply to an open ask says whose turn it is next, and the Inbox files the ask by that, not by who spoke last. Your plain reply
+(`turn` omitted, or `turn: "human"`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
+yet — "dispatched two auditors, back with results", "checking the release branch, back shortly", any working-on-it note — reply with
+`turn: "agent"`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
+`turn: "agent"` for every progress note and `turn: "human"` (the default) only when you need them. A human's reply always hands the
+turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
+`ask_waiting_on`, and every ask read carries it as `waiting_on`.
+
+## Following
+
+An ask has followers: every session that wrote to it — the session that opened it and every session that replied with
+`dispatch_comment({ reply_to_ask })` — plus any session a human adds from the ask card. The ask's answer, edits, resolution, and
+every reply on it reach each follower's own agent topic directly, whether or not the writer was a human and whatever the issue's
+route. The tool result says so (`You follow this ask: its answer and replies reach you directly.`) and carries `details.follows.ask`;
+the host tells you once per ask. Leave a thread you no longer need, or rejoin one, with:
+
+```ts
+dispatch_follow({ ask, action: "follow" | "unfollow" })
+```
+
+`ask` is the full ask id or a `dispatch://KEY/ask/<id>` reference; `dispatch_follow`, `dispatch_edit_ask`, and
+`dispatch_resolve_ask` also take an 8+ hex prefix that is unique among your own open asks, and refuse anything shorter by naming
+those asks. A human may also remove you from the ask card; either way you are
+told with an `ask.follower_removed` notice, and a human adding you arrives as `ask.follower_added`.
+
+No write subscribes you to an issue or document. Following covers your own asks and the threads you joined; everything else on the
+owner — other sessions' asks, comments, messages, status changes — reaches you only if you subscribe to the owner topic yourself.
+Every write result names that line: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` for an issue,
+`envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>` for a project document. The owner topic carries every Dispatch
+event; `notify` only controls agent wake and routed delivery. A human may unsubscribe you from the issue or document header; you
+are told with a `subscription.removed` notice when that happens.
+

package/skills/dispatch/references/document-edits.md

@@ -1,7 +1,7 @@
 # Editing a document
 
 Every document a Dispatch tool writes — an issue's spec, a project document — is edited in place
-with `dispatch_doc_edit`, never re-uploaded. [The Spec](../SKILL.md#the-spec) sends you here for
+with `dispatch_doc_edit`, never re-uploaded. "The Spec" in `skill://dispatch` sends you here for
 the tool's shape, how to target the text you mean, what each operation costs a block, and how to
 reject a stale edit.
 

package/skills/dispatch/references/documents.md

@@ -0,0 +1,148 @@
+# Documents: typed blocks, comments, suggestions, and artifacts
+
+`skill://dispatch` sends you here when you write a typed block (an `:::ask` or a callout), comment on
+or suggest a change to a document, upload an artifact, or get `DOC_SCHEMA`, `INVALID_ASK_BLOCK` or
+`DOC_SERVICE_UNAVAILABLE` back. Changing a document's text, tables included, is
+[Editing a document](skill://dispatch/references/document-edits.md).
+
+## Typed blocks
+
+The server declares typed document blocks at `GET /api/v1/schema/blocks`. Write one only with the
+container-directive form `:::name{#block-id key="value"}` on its own line, ordinary block children,
+and a closing line of as many colons at the same nesting. A typed block directly inside another needs the outer
+one's fence a colon longer (`::::callout{…}` around a `:::callout{…}`), and so does one whose code holds a `:::` line;
+Dispatch writes its fences that way. An unclosed typed block at document level is rejected. For
+a new typed block, omit `#block-id`; Dispatch mints it. When editing an existing typed block, retain
+its id and every rendered attribute. Never copy an existing block's id into new markdown: an id
+names one block, so an insert, upload or suggestion whose markdown names an id the document holds
+outside the text it replaces is refused naming the id: `INVALID_OP` for an insert,
+`INVALID_MARKDOWN` for any other write. To rewrite such a block whole, `delete` it and then
+`insert` the new one carrying its id, anchored on the block before or after it, in that order and
+in one batch: an insert carrying an id the document still holds is refused.
+
+Use only the type names, content rule, attributes, and enum values returned by the schema. Values are
+quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::: {.callout}`, leaf
+`::name` directives, or text `:name` directives; those strings are literal when quoted inside a code
+block. Do not set attributes the schema marks `server: true`; the server ignores them and reasserts
+its authoritative value at settlement.
+
+Questions about a document must be `ask` blocks, never an `Open questions` prose section. An ask
+body is one or more question paragraphs followed by an optional bullet list of options, where each
+item is `Label: description`. A spec, an uploaded document or an uploaded version holding an ask that
+breaks that shape - a code block, heading or quote in it, a paragraph after its options, a second
+list - is refused with `INVALID_ASK_BLOCK`; so is an edit that writes one. An ask someone left
+unreadable in the browser refuses nothing it is carried through unchanged by. For example:
+
+```md
+:::ask{urgency="high" multiple="false"}
+Should we ship the migration?
+
+- Ship: Release the verified change.
+- Hold: Wait for another review.
+:::
+```
+
+When a human answers a decision written as an ask block, the answer lives on that ask. Use
+`dispatch_resolve_ask` when the decision is resolved without a human response, or preserve the
+human's answer; never rewrite the question into its answer or blank its options. An edit that leaves
+an ask block without a question or with a blank option is rejected with `INVALID_ASK_BLOCK`.
+
+## Comments and suggestions
+
+Add feedback with:
+
+```ts
+dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
+```
+
+It returns issue or project-document owner details plus `comment`; a `reply_to_ask` reply also returns `ask` and `follows: { ask }`,
+because replying to an ask makes you one of its followers (see [Following](skill://dispatch/references/asks.md)).
+`ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
+`quote` requires `artifact`; its anchor is pinned to the containing block while retaining the quote
+for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
+`quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
+threads flat. A reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
+question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
+the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
+the human needs to act; see "Asking" in `skill://dispatch`. Comments are edited only by their author from the
+dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
+`dispatch_comment({ reply_to: <id> })`.
+
+Resolve your own review comment once you have addressed it:
+
+```ts
+dispatch_resolve_comment({ comment })
+```
+
+`comment` is the comment id, or a `dispatch://KEY/comment/<id>` or `dispatch://PROJECT/artifact/<slug>/comment/<id>` reference (an
+8+ character id prefix is resolved against the owner's comments). It returns the owner details plus `comment`, and takes no reason —
+say what you did in a `reply_to` first if the thread needs it. The server lets any session or human resolve any open comment, so
+resolve only threads you opened or were asked to close; reopening a resolved thread is human-only (from the dashboard), though your
+reply to it reopens it. Asks are closed with `dispatch_resolve_ask` instead.
+
+An exact replacement for document text is a suggestion (`dispatch_suggest`), never a comment; a
+comment is for a question or a note the human answers in words. A human accepts a suggestion with
+one click and cannot accept a comment, so propose the replacement instead of describing it:
+
+```ts
+dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })
+```
+
+It returns issue or project-document owner details plus `comment`. A human accepts or rejects a suggestion.
+Errors: `TARGET_AMBIGUOUS` (add `occurrence`), `TARGET_NOT_FOUND` (re-read first), `INVALID_ANCHOR`/`ANCHOR_MISSING`/`ANCHOR_ORPHANED`
+(bad, unwritten, or stale quote), `INVALID_MARKDOWN`/`DOC_SCHEMA` (malformed content), `CAP_EXCEEDED`, `ISSUE_CLOSED`.
+Suggest only what the quoted block can hold. The accept, not the suggestion, checks that: an
+accept whose `replace_with` would break an ask block that was readable before it is refused with
+`INVALID_ASK_BLOCK` - a question given a code block, text after an ask's options, a second option
+list, or an emptied question; one that names an id the document holds outside the text it
+replaces, an ask under a held id included, with `INVALID_MARKDOWN`; and one no part of the
+document can hold where it sits (a code block over a table cell's whole text), or whose quote runs
+into an ask or callout from the text before it, with `INVALID_OP`. Either changes nothing: the human sees the reason with no Retry, and the suggestion
+stays open until someone rejects or replaces it.
+
+## Artifacts
+
+Attach an image, diagram, or local file with:
+
+```ts
+dispatch_artifact({ issue?, project?, name, path, summary? })
+```
+
+Or, when the text is already in the call, post a Markdown document directly:
+
+```ts
+dispatch_artifact({ issue?, project?, name: "load-test-results.md", content: "# Load test\n..." })
+```
+
+Exactly one of `issue` and `project` is required. A project upload creates an unlinked project document; it must not include `artifact`.
+Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact` and `version`.
+Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
+with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [Editing a document](skill://dispatch/references/document-edits.md)). Address an existing
+artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
+slug also arrives on `artifact.created` events. Dispatch suffixes a slug two documents would share, so one document's
+filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
+`artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
+
+Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
+dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
+document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
+still belongs inside a fenced code block, where it survives verbatim both ways.
+
+## A document that is reloading
+
+These calls can answer `DOC_SERVICE_UNAVAILABLE` (HTTP 503), because each writes a document inside its
+transaction: `dispatch_doc_edit`; `dispatch_ask` and `dispatch_comment` on a quote; a `dispatch_comment` reply
+in a thread whose first comment is anchored; `dispatch_suggest`; `dispatch_resolve_comment` on an anchored
+comment; `dispatch_artifact` replacing a document that already exists; and, on an ask that lives in a `:::ask`
+block, `dispatch_edit_ask` and `dispatch_resolve_ask`, which write that block. Creating an issue with a spec,
+uploading a new document, `dispatch_request_approval` and `dispatch_message` never answer it, and neither do
+`dispatch_edit_ask` and `dispatch_resolve_ask` on an ask that has no block. It means that document's live room
+failed and is reloading from its durable copy, so the server refused rather than wait for it; your call wrote
+nothing and the document is intact. Nothing retries it for you: the Dispatch client hands a 503 straight back.
+Wait a few seconds and make the same call again. A second refusal in a row is worth telling your human about,
+with the document's reference.
+
+`dispatch_doc_read` can answer it too, though it writes nothing: a read never opens a live room, and waits out
+a room that is reloading, so it is refused only when the document's durable copy cannot be read or decoded.
+Retry it the same way.
+

package/skills/dispatch/references/examples.md

@@ -0,0 +1,82 @@
+# Before and after: an ask, a message, and a draft
+
+`skill://dispatch` sends you here for worked examples: a decision written as clickable options, a
+message that should not be sent, and a draft placed where the human reads it.
+
+## Before / after
+
+Before — a wall of text hides the decision and makes the choices unclickable:
+
+```text
+We need to settle the release gate because the deploy branch has the migration and the
+dashboard changes, I checked the staging result and it is fine except the release notes are
+not reviewed, so should we ship today, wait for docs, or cut the dashboard from this release?
+I think waiting is safest but the customer demo is tomorrow and the list above is probably stale.
+```
+
+After — anchor the decision and make each option a button:
+
+```ts
+dispatch_ask({
+  issue: "LEGION-815",
+  question:
+    "Choose the release gate. Recommendation: ship after release-note review, since the tested deployment is otherwise ready.",
+  options: [
+    { label: "Review notes, then ship", description: "Keeps the release intact and reviewed." },
+    { label: "Ship now", description: "Meets the demo deadline; release notes follow later." },
+  ],
+  urgency: "high",
+  anchor: { artifact: "spec", quote: "Release requires reviewed operator instructions before deployment." },
+})
+```
+
+Before — a progress note that nobody needs, posted where humans look for decisions:
+
+```ts
+dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
+```
+
+After — nothing. The merge is visible on the pull request; the docs work shows up as its own deliverable. Post a message only when
+a human must act or a deliverable is theirs to use:
+
+```ts
+dispatch_message({
+  issue: "LEGION-815",
+  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
+})
+```
+
+Before — a draft the human must read is uploaded as a separate file, the spec only names it, and
+the ask does not point at it, so the reader has to go looking:
+
+```ts
+dispatch_artifact({ issue: "OPS-52", name: "cu-update-2026-09-15.md", content: "Hi team, ..." })
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft (artifact cu-update-2026-09-15.md)" },
+]})
+dispatch_ask({ issue: "OPS-52", question: "Send the customer update as drafted?", options: [...] })
+```
+
+After — the draft is a section of the spec, and the ask anchors there. If it really must be a
+file (something to send as-is), the spec and the ask both link the slug from the upload result:
+
+```ts
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nHi team, ..." },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question: "Send the customer update as drafted?",
+  options: [...],
+  anchor: { artifact: "spec", quote: "Hi team," },
+})
+// or, for a real file — the spec links it where the reader needs it, and so does the ask:
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send as-is: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question: "Send this customer update as-is? dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
+  options: [...],
+})
+```

package/skills/dispatch/references/issues.md

@@ -0,0 +1,213 @@
+# Working an issue: choosing, claiming, status, priority, and the backlog
+
+`skill://dispatch` sends you here when you pick your next issue, claim or release one, get
+`409 ISSUE_CLAIMED`, move an issue's status or priority, reorder a board, reassign an issue, sync a
+project's architecture model, or list or audit a project's backlog.
+
+## Choosing what to work on
+
+When you finish an issue, or are told to work on the next thing, take the top ready issue of the
+whole backlog, across every project: status `todo`, highest priority first, then board rank. There
+are no areas: a standing role, a product owner and a lane each take the top issue like everyone
+else (Sami, 2026-09-27, dispatch://AGENTC-34/ask/01ed2956-73cc-48d2-8ed4-7a86c6d439b1). `todo`
+means ready: specced, unblocked, and waiting on neither a deploy nor a decision. An issue that
+waits on one belongs in `backlog`, with what it waits on said on the issue.
+
+Hold at most three issues in flight (`in_progress`, `testing`, `needs_review` or `retro`), of any
+kind (Sami, 2026-09-27, answering dispatch://AGENTC-34/ask/1aeb8f2e-0950-4eaa-aaac-24286c9dd3ca;
+the question proposed two, and his answer set three). The limit is per agent and has nothing to do
+with the week's priorities (Sami, 2026-09-28, reply a7647eb0 on
+dispatch://AGENTC-393/ask/b773d9f6): the priorities decide only what you pull next. Past three:
+push any unfinished work, say where in one comment on the issue, move it to `backlog` and clear
+its route. Each issue counts on its own; a child does not ride under its parent's slot.
+In-flight issues with no owner at all go
+back to `backlog` as well: no claim or route held by a live session, no Dispatch activity in the
+last day, and no pull request moving on GitHub (an owner working there leaves no Dispatch trace).
+The order keeper sweeps those. Never write the status of an issue that carries the `legion`
+label, or of any issue under one: the Legion daemon writes those statuses, and moving one of its
+admitted roots out of its flow parks the tree and stops its workers.
+
+One agent keeps the backlog's order against those priorities, with Sami
+(dispatch://AGENTC-34/ask/f6780f9e-8b96-49eb-9be7-7c7f2036d5cc). Setting an issue's priority
+stays yours ([Priority is yours to set](#priority-is-yours-to-set)); reordering the board does not.
+When the top of the backlog looks wrong, or a priority's next step is not yet a ready issue,
+publish it to `notifications.role.backlog-order`, which the order keeper holds, instead of
+reordering the board yourself.
+
+## 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). A session's claim there ends
+`· not running` when the live agent registry does not list that session, as the dashboard's chip
+does — that claim is free to take — and `· liveness unknown` when the registry could not be read,
+which says nothing either way. `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 with `dispatch_ask` instead, so the open ask appears in their Inbox, 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
+the daemon writes it), the session doing the work moves it, the way a person moves a card:
+`in_progress` when implementation starts, `testing` when the change is being proven on a
+production-like surface, `needs_review` when its pull request is open and waiting on the merge
+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.
+
+```ts
+// 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", status: "done", reason: "Shipped in owner/repo#7; verified on the production dashboard." })
+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
+```
+
+Closing takes a `reason`, and the tool refuses `status: "done"` without one: it posts the reason on
+the issue as a message, then closes it, because a closed issue refuses messages, comments, and
+artifacts, so a reason left for later has nowhere to go. When the close fails after the post, the
+error names the posted message; after a timeout or a server error it also says the close may have
+landed, so read the issue's status first. A retry points its reason at the posted message rather
+than repeating it.
+
+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, and `dispatch_read` lists it under `External links:`.
+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
+the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
+
+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](#board-rank-priority-and-assignee-on-a-read) describes, through `PATCH /api/v1/issues/{key}`.
+
+## Board rank, priority, and assignee on a read
+
+Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with `{"rank": {"before": "<key>", "after": "<key>"}}`, either neighbor optional and both in the issue's project. A bearer caller also names its own session in that body, `"actor": {"kind": "session", "id": "<your session id>"}`, or the server refuses with `ACTOR_KIND`. They also include nullable coarse priority (`P0` highest through `P3` lowest) and `assignee`: the lowercase GitHub login of the human who answers the issue's asks, or `null` when nobody holds it. `dispatch_read` of an issue prints it as `Assignee: <login>` or `Assignee: unassigned`.
+
+## Reading a project's backlog
+
+To see the shape of a project rather than find a phrase, list its issues:
+```ts
+dispatch_issues({ project, status?, parent?, label?, priority?, route_status?, updated_since?, limit?, offset? })
+```
+Each row carries the issue key, title, status, priority, parent, labels, its open-ask count, and
+when it last changed — a roadmap or backlog pass without opening every issue. Filter with `status`
+(a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
+`null` for an issue with no priority: `[0, 1]` is every P0 and P1), `route_status` (below), or
+`updated_since` (an RFC3339 timestamp, for "what moved this week"). `limit` is the page size, 50 by
+default and 250 at most, and `offset` is where the page starts: repeat with the next offset until a
+page comes back short to list every matching issue.
+
+This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
+`dispatch_issues` when you want every issue in a project and its current state.
+
+### The owner audit
+
+As the owner of a surface, list the project's P0 and P1 issues and staff or close each one nobody
+has started:
+```ts
+dispatch_issues({ project, priority: [0, 1], limit: 250 })
+```
+Every unclaimed row in `triage`, `icebox`, `backlog` or `todo` is a decision: someone takes it and
+builds it, or it closes. A row in `in_progress`, `testing`, `needs_review` or `retro`, or one that
+carries a claim, is work under way ([Issue status is yours to move](#issue-status-is-yours-to-move))
+and is not re-staffed. A todo with a finished spec reads as queued work that nobody is doing
+(LEGION-173 sat in todo for two weeks with a complete spec; AGENTC-1010's v4 plan sat in backlog
+with nobody building it).
+
+A close that says the defect cannot happen cites the code that makes it impossible. An issue
+closed because a rewrite forecloses it names the file and line in the rewrite that does so; a
+close that cannot name one is not foreclosed, it is unread. The cheapest way for a rewrite to reach
+parity is to port the code, defect included: LEGION-211's bare `git worktree prune`, filed against
+the TypeScript daemon, had been ported into the Go coordinator and was live in production.
+
+The audit finds four shapes:
+
+- **Unstaffed work.** A plan or measurement exists, and no one is building it.
+- **Unrecorded delivery.** An issue not yet in `testing` or `done`, claimed or not, has a merged PR
+  naming it. Check the change live, then move the issue (AGENTC-1033 sat at `triage` after its fix,
+  agent-c #20367, merged).
+- **Unrecorded practice.** Someone does the issue's work by hand, more than once, while the issue
+  sits in backlog (OPS-132, done by hand on every migration merge). It leaves no plan and no PR to
+  find; the tell is your own messages. Doing something by hand more than once means an issue is
+  wearing the wrong status.
+- **Unreachable route.** An open issue whose route names a role nobody holds, or a session that is
+  not running, reaches nobody, whatever its priority, and the priority filter above never finds
+  it. List it on its own:
+  ```ts
+  dispatch_issues({ project, route_status: "no_holder", limit: 250 })
+  ```
+  Each row reads `route role:sre (nobody holds it right now)` or `route session:<id> (that session
+  is not running right now)`. That is one read of the listener, and one read is a restart gap as
+  often as a vacancy: an agent box that restarts or resumes keeps the session id, but the session
+  is absent from the listener for minutes, and its role with it. On 2026-09-27, 58 of 63 session
+  routes one read showed as unreachable pointed at a single session that was moving between boxes.
+  So a route is unowned only when it is `no_holder` on two reads at least ten minutes apart: list
+  again after ten minutes and act on the issues both lists name. Confirm with the second
+  `dispatch_issues` read, not `envoy_role_get`: a role lookup releases the claim of a holder whose
+  session is absent from the registry as it answers. Then staff the role, re-route the
+  issue to a live holder, or clear the route and assign it (AGENTC-1065, a P2 production listener
+  503, sat routed to an unheld `role:sre` with no assignee). `route_status: "unknown"` means the
+  listener did not answer, so a route could not be judged; a `no_holder` filter refuses rather
+  than answer an empty list then.
+
+Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
+are found by running the check, not by noticing them.
+
+## Syncing a project's architecture model
+
+Import a project's architecture model from its configured source repository now (a human configures the source in Settings):
+```ts
+dispatch_architecture_sync({ project: "CORE" })
+```
+It returns the imported commit, or the recorded error when the model was rejected — the previous model stays up. Without a configured source it answers 404 `SOURCE_NOT_FOUND`.
+