@sjawhar/opencode-legion-envoy 3.2.8 → 3.2.10

package/dist/src/server.js

@@ -14117,7 +14117,7 @@ var dispatchToolSpecs = [
       artifact: z2.string().describe("Project document artifact id, slug, or filename containing the quoted text; optional when ref names it.").optional(),
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z2.string().describe("Exact document text to replace."),
-      replace_with: z2.string().describe("Replacement text."),
+      replace_with: z2.string().describe("Replacement text; a CR LF or a lone carriage return in it is written as a line feed."),
       body: z2.string({ max: 2000 }).describe("Optional rationale, at most 2,000 characters.").optional(),
       occurrence: z2.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional()
     }),
@@ -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 - 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}`,
+    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 - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. ` + "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. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + `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,15 +14151,15 @@ 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: inside a code block, the code's literal text as sent (line breaks at its end do not survive a read); 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(),
+        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); 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. A CR LF or a lone carriage return in it is written as a line feed.").optional(),
         occurrence: z2.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
-        markdown: z2.string().describe("Markdown to insert.").optional(),
+        markdown: z2.string().describe("Markdown to insert; a CR LF or a lone carriage return in it is written as a line feed.").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(),
         before: z2.string().describe(`Insert or move before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),
         block: z2.string().describe("Block id for retype, delete, move, delete_row, or delete_column: the #id of a typed block, or an id from GET /api/v1/artifacts/{id}/blocks.").optional(),
         index: z2.number({ int: true, min: 0 }).describe("Zero-based row or column index for delete_row or delete_column.").optional(),
         type: z2.string().describe("Typed block name for retype.").optional(),
-        attributes: z2.unknown().describe("Typed block attributes for retype.").optional()
+        attributes: z2.unknown().describe("Typed block attributes for retype; a CR LF or a lone carriage return in a string value is written as a line feed.").optional()
       }, { strict: true })).describe("Flat tagged edits; an operation takes only the keys below, a misspelled one is refused rather than ignored, and the server validates the fields its op requires."),
       precondition: z2.object({
         document: z2.string({ min: 1 }).describe("Token for the exact canonical document returned by dispatch_doc_read.").optional(),
@@ -14206,7 +14206,7 @@ var dispatchToolSpecs = [
       project: z2.string().describe("Project key for an unlinked document.").optional(),
       name: z2.string().describe("Artifact filename shown in Dispatch."),
       path: z2.string().describe("Local path to the file to upload.").optional(),
-      content: z2.string().describe("Inline text to store as a Markdown document.").optional(),
+      content: z2.string().describe("Inline text to store as a Markdown document; a CR LF or a lone carriage return in it is stored as a line feed.").optional(),
       summary: z2.string().describe("Optional version summary.").optional()
     }),
     validation: {
@@ -16907,7 +16907,9 @@ ${followsAsk(askOwner)}`,
       const head = nothingChanged ? `Applied ${edited.applied} ops${retypedText}; nothing changed (${versionText})` : `Applied ${edited.applied} ops${retypedText} (${versionText})`;
       const unchangedOps = edited.unchanged_ops ?? [];
       const unchangedText = unchangedOps.length === 0 ? "" : `; ${unchangedOps.length === 1 ? "operation" : "operations"} ${unchangedOps.join(", ")} changed nothing`;
-      const applied = `${head}${unchangedText}`;
+      const lostOps = edited.lost_ops;
+      const lostText = lostOps === undefined || lostOps !== null && lostOps.length === 0 ? "" : lostOps === null ? "; could not confirm this edit survived, because the live document is being reloaded \u2014 re-read it" : `; ${versionText} carries text the live document no longer has: a concurrent change removed what ${lostOps.length === 1 ? "operation" : "operations"} ${lostOps.join(", ")} wrote \u2014 re-read the document`;
+      const applied = `${head}${unchangedText}${lostText}`;
       const adviceLines = renderAdvice(input.tool, resolvedTopic(resolved).label, edited.advice, {});
       const tokenTrailer = edited.token === undefined ? [] : [`Document token: ${edited.token}`];
       return {
@@ -16921,6 +16923,7 @@ ${followsAsk(askOwner)}`,
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number },
           ...nothingChanged ? { changed: false } : {},
+          ...lostOps === undefined ? {} : { lost_ops: lostOps },
           ...edited.token === undefined ? {} : { token: edited.token },
           ...edited.advice === undefined ? {} : { advice: edited.advice }
         })

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -571,6 +571,10 @@ nothing and the document is intact. Nothing retries it for you: the Dispatch cli
 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.
+
 ## Typed blocks
 
 The server declares typed document blocks at `GET /api/v1/schema/blocks`. Write one only with the

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

@@ -9,8 +9,8 @@ reject a stale edit.
 dispatch_doc_edit({ issue?, project?, artifact, ops, precondition?, summary? })
 ```
 It returns issue or project-document owner details plus `applied`, optional `version`, `changed`,
-`unchanged_ops`, and the document token this edit produced, rendered as a `Document token: <token>`
-line. `ops` is an array of this exact `EditOp` shape:
+`unchanged_ops`, `lost_ops`, and the document token this edit produced, rendered as a
+`Document token: <token>` line. `ops` is an array of this exact `EditOp` shape:
 
 ```ts
 type EditOp = {
@@ -66,15 +66,17 @@ 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` 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
+alone. An empty `with` deletes the matched text on purpose; a list item, quote, typed block or footnote definition left
+holding only the emptied paragraph keeps it, and reads back holding it. Emptying a task item's first paragraph while
+another block follows it in the item is `INVALID_OP`, since the browser editor reads no such item as a task. 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. A line of colons in code inside a typed block is kept: Dispatch writes
 that typed block's fence longer than any such line the browser editor would end it at. 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
+`***`). A CR LF or a lone carriage return in any text you write - an insert's markdown, a `with` in text or in code,
+a suggestion, an upload or a spec - is stored as a line feed, as the browser editor reads both. 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.
 
@@ -115,7 +117,7 @@ block before or after it. The delete is what costs the id (below); a typed block
 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 where the block allows it, so a `replace` whose `with` you meant to fill
+`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.
 
 A batch that leaves the document's semantic identity unchanged — including its inline anchor marks, so an edit that only orphans a
@@ -158,6 +160,17 @@ token; Dispatch applies no part of that batch. It is the hashline `#TAG` propert
 not line numbers: canonical Markdown lines shift under concurrent edits and rendering changes, while block ids
 survive moves and retyping.
 
+A browser editing the same document while your edit is in flight never makes your edit a silent
+no-op. The two changes merge, and a human's deletion of the paragraph you are rewriting wins — but
+you are told. `409 EDIT_LOST_TO_CONCURRENT_CHANGE` means the whole batch was refused and nothing
+was written: re-read the document and decide again, as with `PRECONDITION_FAILED`. A success whose
+`lost_ops` names operations means the version was written and the live document already lacks what
+those operations wrote, because the deletion landed after the version: re-read before building on
+it. `lost_ops: []` is the ordinary outcome, and a result that says it could not confirm the edit
+survived means the room is reloading — re-read. An operation that only removes text (`delete`,
+`delete_row`, `delete_column`, a `replace` that shortens) is never reported lost: a concurrent
+deletion cannot undo a removal.
+
 `retype` turns the paragraph or typed block with `block` into the named typed `type` in place. It keeps the
 block id, keeps a typed block's body, and uses `attributes` for client-owned typed attributes. Use it when
 an existing paragraph is the question that should become a decision.

package/skills/legion-worker/SKILL.md

@@ -307,18 +307,46 @@ this proof.
   reviewer answers each thread it opened with exactly one of `Accepted: fixed in <commit> — <one line>`,
   `Accepted: not a defect — <reason>`, or `Still open: <what remains>`; nothing else is an
   acceptance, and nobody replies after an `Accepted:` (any later reply that is not itself an
-  `Accepted:` — the opener's own follow-up included — leaves the thread open, since the command
-  reads only the newest comment). The review App can reply on a thread but cannot resolve it:
+  `Accepted:` — the opener's own follow-up included — leaves the thread open, because resolution
+  considers only the newest comment). The review App can reply on a thread but cannot resolve it:
   GitHub grants resolving a review thread to the pull request's author, and the implementer opens
-  every Legion pull request (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps). So the
-  **implementer** runs `legion threads resolve --pr <number> --repo <owner>/<repo>` before every
-  push that answers a review (the corrective push and the final `.legion/` deletion push) and
-  pastes its output into the `Threads` section. The command resolves each unresolved thread
-  whose newest comment is the opener's own `Accepted:` reply, one `resolveReviewThread` per
-  thread, prints `resolved <url>` or `left open <url> — newest reply by <login> is not an acceptance`,
-  and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one; report that
-  exit to the architect, which opens an ask for a human to resolve the thread by hand —
-  never skip it silently. The merger runs the same command once more before publishing READY
+  every Legion pull request (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps).
+  When `LEGION_GRANT_FILE` or `LEGION_GRANT` is set, use `legion threads resolve --pr <number> --repo <owner>/<repo>`; when neither is set, use `gh api graphql`
+  with the session's GitHub credential and the fallback below.
+  In a Legion pane, the **implementer** runs the command before every push that answers a review
+  (the corrective push and the final `.legion/` deletion push) and pastes its output into the
+  `Threads` section. The command resolves each unresolved thread whose newest submitted comment is
+  the opener's own `Accepted:` reply, one `resolveReviewThread` per thread, prints `resolved <url>`
+  or `left open <url> — newest reply by <login> is not an acceptance`, and exits 1 naming the
+  thread's URL and GitHub's message when GitHub refuses one.
+
+  Without a grant, page through `reviewThreads`, skip `isResolved: true`, and compare the opener
+  with the newest comment. Query shape, inside `repository { pullRequest { … } }`:
+
+  ```graphql
+  reviewThreads(first: 100, after: $after) {
+    pageInfo { hasNextPage endCursor }
+    nodes {
+      id isResolved
+      opener: comments(first: 1) { nodes { author { login } } }
+      newest: comments(last: 1) { nodes { author { login } body state } }
+    }
+  }
+  ```
+
+  Resolve only when the newest comment is submitted, its `author { login }` equals the opener's,
+  and its `body`, after removing leading spaces, tabs, CR, and LF, begins `Accepted:`. For each
+  such thread:
+
+  ```graphql
+  mutation($threadId: ID!) {
+    resolveReviewThread(input: { threadId: $threadId }) { thread { isResolved } }
+  }
+  ```
+
+  Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
+  a refused resolution to the architect, which opens an ask for a human to resolve the thread by
+  hand — never skip it silently. The merger runs the command once more before publishing READY
   and does not publish while any `left open` line remains.
 - **Correctness fixes land in this PR; cleanup is one named fast-follow.** A finding that
   changes behavior, hides an error, or breaks a gate is fixed here — never deferred.