@sjawhar/opencode-legion-envoy 3.2.2 → 3.2.4

package/dist/src/server.js

@@ -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.2",
+  "version": "3.2.4",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -580,7 +580,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 +655,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
 

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

@@ -71,9 +71,11 @@ launcher, and started you with `LEGION_CONTROLLER=1` and the same environment a
 carries, so nothing changes in how you handle wakes. Under the TypeScript daemon the extension
 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, then claims the role. 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
+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
+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.
 Exiting it leaves the project without a controller until the operator runs the command again —
 the TypeScript daemon logs `controller not registered; run legion controller start` once per
@@ -81,6 +83,20 @@ boot-timeout interval and launches nothing itself. `legion state` and `legion st
 <status>` work here over `LEGION_DAEMON_URL`. A second `legion controller start` replaces you: it
 mints a new secret, so your grants stop working and the role moves to the new session.
 
+### What happened before you started (Go daemon)
+
+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.
+
 ## Deployment instructions
 
 Deployment instructions, when present, are the operator's standing rules for this repository —
@@ -116,6 +132,8 @@ quoted here.
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
 | READY packet seen on a Dispatch issue (via issue subscription) | READY line + gate facts | No action: a human merges; the merger has already notified the queue role if the project has one |
 | `worker-recovered` (role `architect`) from the daemon | issue, fromRef | A root architect's tree volume was lost; it restarted as a new session. Verify the tree is active in `legion state` and that the architect posts its next step on the issue within one resync interval; otherwise treat it as an anomaly. |
+| `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `legion state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `legion status <root> backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
+| `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `legion state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`legion status <root> backlog`, then `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
 | Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion status <root> todo`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |