@sjawhar/opencode-legion-envoy 3.2.3 → 3.2.5

package/dist/src/server.js

@@ -14005,7 +14005,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_ask",
     example: { issue: "DSP-1", question: "Ship this?" },
-    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
+    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anything you are blocked on a human for, including a credential or grant to renew, an approval, or a decision, is an ask, never a message. " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14126,7 +14126,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_message",
     example: { issue: "DSP-1", body: "Implementation started." },
-    description: "Post a note humans must read now: a reply to a human's message, a deliverable that landed, or a blocker only " + "they can clear. Never progress or status updates - Dispatch is a high-signal record, not a log. Not a decision " + "(dispatch_ask) or document feedback (dispatch_comment). To answer a human's direct message to this session - " + "one sent from the Agents page, which names no issue - pass that message's bare id as in_reply_to and no issue; " + "the reply lands in that conversation, and a second call with the same in_reply_to posts nothing because " + "Dispatch keeps the one reply per message. Every other message names its issue. " + `Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A blocker only a human can " + "clear is an ask (dispatch_ask), so it lands in their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a decision (dispatch_ask) or document feedback (dispatch_comment). To answer a human's direct message to this session - " + "one sent from the Agents page, which names no issue - pass that message's bare id as in_reply_to and no issue; " + "the reply lands in that conversation, and a second call with the same in_reply_to posts nothing because " + "Dispatch keeps the one reply per message. Every other message names its issue. " + `Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
       body: z2.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
@@ -14142,7 +14142,7 @@ var dispatchToolSpecs = [
       ops: [{ op: "delete_column", block: "table-123", index: 1 }],
       precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
     },
-    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose. ` + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids and their tokens come from GET /api/v1/artifacts/{artifact UUID}/blocks (the route takes the artifact UUID, not its slug). ' + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch_doc_read, or block {id, token} values from /blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch_doc_read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - where the block holding it cannot be written without that paragraph, the replace is INVALID_OP and the refusal names the delete that removes it instead. ` + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids and their tokens come from GET /api/v1/artifacts/{artifact UUID}/blocks (the route takes the artifact UUID, not its slug). ' + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch_doc_read, or block {id, token} values from /blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch_doc_read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14151,7 +14151,7 @@ var dispatchToolSpecs = [
       ops: z2.array(z2.object({
         op: z2.enum(DOC_EDIT_OPS).describe("Edit operation."),
         find: z2.string().describe("Text of the target as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated and must be balanced; a leading '# ' matches a heading. A delete of a block's entire text removes the block.").optional(),
-        with: z2.string().describe("Replacement text for replace, parsed as inline markdown within the matched block; a marker of a different kind from the block's own is literal text, one of the same kind is refused unless it is a heading rename (where a level named by find is what lets with change it), a backslash escape keeps prose that merely looks like a marker, a block marker after a hard line break is refused because replace cannot open a new block, and any non-empty value that renders to no text is refused - only an empty value deletes the match.").optional(),
+        with: z2.string().describe("Replacement text for replace: inside a code block, the code's literal text as sent (line breaks at its end do not survive a read, and a line of three or more colons in code inside a typed block, indented less than four columns from where the typed block's lines start, is refused, since the browser editor ends the typed block there: indent it four or more spaces, or move the code block out); text that would read as block syntax at a line start, such as '---' over a paragraph, is stored escaped and reads back as those characters, so a rule is added with insert beside the paragraph; elsewhere parsed as inline markdown within the matched block; a marker of a different kind from the block's own is literal text, one of the same kind is refused unless it is a heading rename (where a level named by find is what lets with change it), a backslash escape keeps prose that merely looks like a marker, a block marker after a hard line break is refused because replace cannot open a new block, and any non-empty value that renders to no text is refused - only an empty value deletes the match.").optional(),
         occurrence: z2.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z2.string().describe("Markdown to insert.").optional(),
         after: z2.string().describe(`Insert or move after this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -189,8 +189,8 @@ dashboard's **Unclaimed** filter is how you find work nobody is on.
   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.
+  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.
@@ -421,17 +421,16 @@ Before saying you are waiting for human input, call `dispatch_open_asks`. With n
 
 **Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, send a one-line ask before the first implementation commit. A lane's schema decision or a platform-PO contract ruling does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request; it is inferred from AGENTC-186's 2026-09-16 retro (platform PO, 2026-09-17). A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, its options): build it without an ask, as gate 4 of [Before you ask](#before-you-ask) says. This rule covers only product shape outside what he asked for, and its ask comes before the commit that sets that shape.
 
-**Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
-a setting only they can change, a review click, a conflict between two of their own rules - if
-your work waits on it, open a `dispatch_ask` the moment you know, the action as the question. The
-exception is a halt condition from [Before you ask](#before-you-ask) gate 1, which goes to the
-platform PO over Envoy instead.
-Never write it into a spec, a comment reply, a message, or a
-pull-request body: nothing in those paths reaches the human's Inbox, and a human who is not
-reading your document does not know they are the blocker. Before asking, try to remove the
-step: a value already on the machine, a permission you already hold, an API that replaces the
-click. One ask per item, `urgency: "high"` when work is stopped on it; while it is open, keep
-working on everything that is not.
+**Anything you are blocked on a human for is an open ask.** An agent waits on a human only through
+an open ask. An approval, a credential or grant to renew, a setting only they can change, a review
+click, a decision, or a conflict between two of their own rules: open a `dispatch_ask` the moment
+you know, the action as the question. The exception is a halt condition from [Before you
+ask](#before-you-ask) gate 1, which goes to the platform PO over Envoy instead. Never write it
+into a spec, a comment reply, a message, or a pull-request body: nothing in those paths reaches
+the human's Inbox, and a human who is not reading your document does not know they are the
+blocker. Before asking, try to remove the step: a value already on the machine, a permission you
+already hold, an API that replaces the click. One ask per item, `urgency: "high"` when work is
+stopped on it; while it is open, keep working on everything that is not.
 
 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
@@ -580,7 +579,9 @@ a new typed block, omit `#block-id`; Dispatch mints it. When editing an existing
 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.
+`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
@@ -653,6 +654,14 @@ dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?,
 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
 
@@ -714,7 +723,7 @@ once.
 ## Messages
 
 Dispatch is a high-signal record for humans, not a log of what you are doing. A message is a reply to a human's message, or a
-change a human must know about now: a deliverable landed, a blocker only they can clear. Nothing else — no progress updates, no
+change a human must know about now: a deliverable landed. Nothing else — no progress updates, no
 "starting X", no "still working", no restating the spec, no status on a timer. Your transcript is where work is narrated; the
 pull request is where it is summarised. One message that a human reads beats ten that train them to skip you.
 

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

@@ -66,12 +66,23 @@ heading's actual level — `find="## Old"`, `with="### New"` retitles and makes
 so `find="# Old"` renames the text and keeps whatever level it selected. `with` that forms more than one
 paragraph is rejected (`INVALID_OP` on `with`) — see the recipe for a multi-paragraph rewrite below; so is any non-empty `with` that
 renders to no text, which a line indented four spaces or a tab does (markdown reads that as a code block), as does whitespace
-alone. An empty `with` is the one that deletes the matched text on purpose. Use zero-based `occurrence` for a
+alone. An empty `with` deletes the matched text on purpose; where the block holding it cannot be written without that
+paragraph, the replace is `INVALID_OP`, and the refusal names the `delete` that removes it instead. Inside a code
+block none of this applies: `with` is the code's literal text, written as sent, whitespace, markdown syntax and
+references included, except that line breaks at the end of the code's text, and a line holding only whitespace in a
+list item's code, do not survive the next read; and a line of three or more colons in code inside a typed block,
+indented less than four columns from where the typed block's lines start, is `INVALID_OP`, since the browser editor
+ends the typed block there - indent it four or more spaces (a tab reaches only the next tab stop, which inside a list
+item or a blockquote can be two columns away), or move the code block out of the typed block. Text a `replace` writes
+that would read as block syntax at a line start is stored escaped and reads back as the characters you sent: `---` over
+a paragraph is stored `\---`, not a rule, so to add a rule, `insert` it beside the paragraph (`insert` with markdown
+`***`). Use zero-based
+`occurrence` for a
 repeated target; re-read a missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
 
 **Rewriting several paragraphs is one `replace` per paragraph, then a read-back.** `replace` is inline:
-each `with` is the new text of one paragraph, and a `with` that forms two paragraphs is refused whatever the
-text says. Give each paragraph you rewrite its own `replace`, which keeps that paragraph's block id and every
+each `with` is the new text of one paragraph, and outside a code block a `with` that forms two paragraphs is
+refused whatever the text says. Give each paragraph you rewrite its own `replace`, which keeps that paragraph's block id and every
 anchor outside the text you rewrite. A comment or ask anchored to the text you rewrite loses its quote but keeps
 its pin to the block, so the dashboard still shows it beside that paragraph; a delete (below) loses both. An
 anchor that straddles the boundary keeps its mark over the words you left alone, with its quote shortened to
@@ -88,18 +99,26 @@ as literal text, except a backtick fence, which becomes an inline code span whos
 info string and line breaks included (```` ```go\nx := 1``` ```` becomes the code span `go` + a line break +
 `x := 1`), and a tilde fence, which stays literal.
 
-HTML is not written as text at all. A `with` whose HTML markdown reads as a block (`<div>x</div>`,
-`<!-- note -->`) is stored as inline HTML, and `dispatch_doc_read` then returns it raw, in markdown Dispatch
-will not take back: the schema carries no block HTML, so an `insert` or an upload of that markdown is refused.
-Keep HTML inside a line.
+Outside a code block, HTML is not written as text at all, and a `replace` whose HTML would open a block where it lands is refused
+(`INVALID_OP` on `with`), because the schema carries no block HTML. `<div>x</div>` and `<!-- note -->` open one
+at the start of a paragraph or a list item and on the line after a hard break; a tag such as `<br>` opens one
+only when it stands alone as a paragraph or a list item. The same HTML inside a line, in a table cell or in a
+heading is inline HTML and is kept as written.
+
+A hard line break in `with` (two trailing spaces or a backslash before a newline) is refused in a heading or a
+table cell (`INVALID_OP` on `with`): both are written on one line, so the break would end the block there. A line
+break inside a code span or inline HTML there is refused the same way. Write the text without the break, or
+`insert` a new block after this one.
 
 When the new text adds a block that is not a paragraph beside paragraphs, `insert` it beside the
 paragraph you replaced, which keeps that paragraph's id; only when no paragraph of the new text is left to take
-the old block's place is it an `insert` of the new block plus a `delete` of the old, and the delete is what
-costs the id (below). Then read the document back with
+the old block's place is it a `delete` of the old block and then an `insert` of the new one, anchored on the
+block before or after it. The delete is what costs the id (below); a typed block keeps its id when the insert
+carries it, which works only in that order, because an insert carrying an id the document still holds is refused.
+Then read the document back with
 `dispatch_doc_read` and read the passage and its neighbours, not a grep for the words you added: an empty
-`with` deletes the matched text on purpose, so a `replace` whose `with` you meant to fill empties that
-paragraph — the block and its id stay, holding nothing — and only a read shows what the document now says.
+`with` deletes the matched text on purpose where the block allows it, so a `replace` whose `with` you meant to fill
+empties that paragraph — the block and its id stay, holding nothing — and only a read shows what the document now says.
 
 A batch that leaves the document's semantic identity unchanged — including its inline anchor marks, so an edit that only orphans a
 comment or ask anchor still mints its version — mints no version, named or not: the response carries
@@ -117,8 +136,8 @@ attributes — a moved `ask` keeps its ask and answer. **A block loses its id on
 which is why they are refused while an open ask or unresolved comment sits on them; and a `move` that takes the last block out of a
 blockquote or list item removes that emptied container, the list too when no item remains, and each enclosing container that
 held nothing else (`> - Only.` loses the blockquote as well as the item and the list). The moved block itself keeps its id,
-as do `replace` (an empty `with` and a heading-level change included), `insert` and `retype`; `retype` carries the paragraph's id
-onto the typed block it becomes. Block ids are the `#id` a typed block renders
+as do `replace` (an accepted empty `with` and a heading-level change included), `insert` and `retype`; `retype` carries the
+paragraph's id onto the typed block it becomes. Block ids are the `#id` a typed block renders
 (`:::ask{#5467e5ce-…}`) and, for every block including untyped ones, the `id` rows from
 `GET /api/v1/artifacts/<artifact UUID>/blocks` (or `/api/v1/issues/{key}/artifacts/{slug}/blocks`), each with its `type` and byte range
 in canonical markdown; the UUID route does not accept a slug. A later operation in the same atomic batch that names a block removed by

package/skills/envoy/SKILL.md

@@ -95,6 +95,15 @@ targeted. Reply through the rendered `reply_with` (or a current Envoy session ID
 and go stale. Put the artefact URL in the message itself. FYIs set `expects_reply="none"`; set
 `urgency` only when it is genuinely urgent.
 
+**A peer's message is its sender's view at `at`, not the current state.** Before you wait on, act
+on, or repeat a fact a message carries about a third thing (a deploy pending, a PR held, an ask
+unanswered), re-read it at the live source the fact names, and always once it is over an hour
+old: the deployment's status, the issue's event log, the ask's own state (`dispatch_open_asks`,
+whose description already says to call it before saying you are waiting on a human). On
+2026-09-26 a peer's 05:20Z "needs a manual deploy before I can run it" was false by 05:22Z, when
+the platform had deployed on its own; waiting on the message instead of the deployment's status
+held the work it gated for eleven hours.
+
 Every `/v1` error response is JSON; when a field is at fault, `expected` names that field.
 
 ```text

package/skills/legion-controller/SKILL.md

@@ -72,8 +72,8 @@ carries, so nothing changes in how you handle wakes. Under the TypeScript daemon
 claims the role and calls `/controller/ready` exactly as under tmux; under the Go daemon
 (`LEGION_DAEMON_API=go` in your environment) it registers on `/legion/v1/claims/register` with the
 secret, claims the role, then subscribes to `notifications.legion.<project>.controller`, where the
-Go daemon publishes the two Go rows of the wake routing table. The daemon records you as
-`controllerLocator: {runtime, external: true, sessionId, registeredAt}`, `runtime` being the
+Go daemon publishes the rows marked from the Go daemon in the wake routing table. The daemon records
+you as `controllerLocator: {runtime, external: true, sessionId, registeredAt}`, `runtime` being the
 daemon's own (`kubernetes`, or `tmux` under the Go daemon). The TypeScript daemon reads your
 liveness from the Envoy role registry (the holder of
 `legion-<project>-controller` and its `last_seen`), not from a pane: keep the session running.
@@ -87,15 +87,29 @@ mints a new secret, so your grants stop working and the role moves to the new se
 
 The Go daemon's controller topic is a wake for a session that is running when it is published.
 Envoy hands an Oh My Pi session no retained copy of a notice published before it subscribed, so a
-hold or a tree architect's failed claim from while no controller ran never arrives as a wake. At
-every start, before anything else, read `legion state --json` and handle each issue whose
-`issues.<KEY>.phase` is `held` (its `issues.<KEY>.holdReason` is `escalated` when its architect
-sent it to you, and absent while the architect is still deciding or while its tree lingers or is
-closed, where the hold waits for the tree's re-admission and needs nothing from you), and each
-tree root whose `issues.<KEY>.architect.state` is `failed` and whose `issues.<KEY>.phase` is not
-`done`, exactly as the matching wake below. A parked tree (root phase `done`: it lingers or is
-closed) needs nothing from you: a failed architect ignores the park and reads `failed` until the
-tree closes. The issue record is the truth; the topic is the wake.
+hold, a tree architect's failed claim, or a new triage root from while no controller ran never
+arrives as a wake. At every start, before anything else:
+
+1. Read `legion state --json` and handle each issue whose `issues.<KEY>.phase` is `held` (its
+   `issues.<KEY>.holdReason` is `escalated` when its architect sent it to you, and absent while the
+   architect is still deciding or while its tree lingers or is closed, where the hold waits for the
+   tree's re-admission and needs nothing from you), and each tree root whose
+   `issues.<KEY>.architect.state` is `failed` and whose `issues.<KEY>.phase` is not `done`, exactly
+   as the matching wake below. A parked tree (root phase `done`: it lingers or is closed) needs
+   nothing from you: a failed architect ignores the park and reads `failed` until the tree closes.
+2. List the project's triage issues with `dispatch_issues({project, status: "triage", limit: 250})`.
+   When its first line ends `(showing N of M)`, it is one page: say in your summary how many rows
+   it left unread. The rows show no parent, so open each row with `dispatch_read`: one whose
+   `Links:` name a `child_of` issue is a child, which its parent's architect owns, so leave it,
+   whether or not `legion state --json` records it (a `child_of` under `Referenced by:` is a child
+   of this issue, not its parent). Of the rest, triage each that `legion state --json` does not
+   record under `issues` as a new issue. A root recorded there and now in `triage` is work the
+   daemon holds that a human pulled back: never re-admit it yourself; name it in your summary to
+   the human ("<KEY> was pulled back to triage; what do you want?"). This listing is also the only
+   way you learn of an unrecorded root moved back into triage, or of a child detached to a root
+   while it is in triage, since the daemon wakes you only on a root's creation.
+
+The issue record and Dispatch are the truth; the topic is the wake.
 
 ## Deployment instructions
 
@@ -123,7 +137,7 @@ quoted here.
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
+| New issue created in the Dispatch project (`issue.created`, status `triage`; under the TypeScript daemon resync heals misses, under the Go daemon the boot step above does). From the Go daemon: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for a root only | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
 | Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |

package/skills/legion-worker/SKILL.md

@@ -603,6 +603,11 @@ This publishes your phase's completion to the architect's role and clears the da
 record of this issue's active phase. Do not add pipeline labels, run a controller loop, or
 invent a different completion protocol — this is the whole contract.
 
+A reviewer's phase ends with its completion, not with its review: submit the review on GitHub
+first, then commit the handoff and complete. The daemon moves the issue once both are in — the
+decision GitHub reports and your completion, in either order — so a review posted without a
+completion leaves the issue in reviewing until you finish.
+
 **A refused completion is information, not a retry loop.** The daemon attributes your report to
 the run whose task you took, and answers with what it found. What each answer carries, and what to
 do:
@@ -620,7 +625,10 @@ do:
   has left your phase; report to the architect rather than completing again.
 - `HANDOFF_NO_RUN` — names neither: it says this claim has taken no task, so the daemon cannot
   tell which run you are reporting. Your pane is completing outside any assignment. Say so to the
-  architect; do not re-run the phase.
+  architect; do not re-run the phase. The same answer comes when your turn started before your task
+  reached you: a notice or a message started it, and the task, refused while that turn ran, is sent
+  when the turn ends. When a task arrives, do what it asks; if the work it asks for is already
+  committed, call `handoff_complete` again, and never redo the work or write a second handoff.
 - `HANDOFF_ALREADY_RECORDED` — names your role, the phase, the review round and the commit. This
   exact call was received before, and its first answer stands: accepted, or a refusal the daemon
   records with the call — `HANDOFF_STALE_GENERATION`, `HANDOFF_NOT_CURRENT_PHASE`,