@sjawhar/opencode-legion-envoy 3.11.4 → 3.12.0

package/dist/src/server.js

@@ -13917,6 +13917,16 @@ var messageValidation = {
   },
   message: "issue is required unless in_reply_to names a message delivered to this session, which is the one message with no issue."
 };
+var readOwner = documentOwnerValidation(true);
+var readValidation = {
+  check: (value) => {
+    const input = value;
+    if (typeof input.message !== "string")
+      return readOwner.check(value);
+    return input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
+  },
+  message: `${readOwner.message} message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it.`
+};
 var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
 function componentsArgument(z2) {
   return z2.object({
@@ -14141,7 +14151,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 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}`,
+    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. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch_read({message}) reads " + "that conversation back. 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."),
@@ -14235,14 +14245,15 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_read",
     example: { issue: "DSP-1" },
-    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply ref, issue, or project plus artifact. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + OWNER_REFERENCE,
+    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch_doc_read instead. Supply ref, issue, " + "or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
       artifact: z2.string().describe("Project document artifact id, slug, or filename.").optional(),
-      ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional()
+      ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
+      message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: readValidation
   },
   {
     name: "dispatch_search",
@@ -15210,8 +15221,8 @@ class DispatchClient {
   async message(issue2, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue2), "messages"], input);
   }
-  async messageReply(id, input) {
-    return this.#json("POST", ["api", "v1", "messages", id, "reply"], input);
+  async messageReply(id, input, options = {}) {
+    return this.#json("POST", ["api", "v1", "messages", id, "reply"], input, options.followUp === true ? { follow_up: "true" } : undefined);
   }
   async getMessage(issue2, id) {
     return this.#json("GET", [
@@ -15223,6 +15234,9 @@ class DispatchClient {
       id
     ]);
   }
+  async getMessageThread(id, session) {
+    return this.#json("GET", ["api", "v1", "messages", id], undefined, { session });
+  }
   async artifact(issue2, input) {
     const artifactPath = ["api", "v1", "issues", await this.#resolveIssue(issue2), "artifacts"];
     if ("content" in input)
@@ -15897,6 +15911,13 @@ function argumentProblems(tool, args) {
       }
       break;
     }
+    case "dispatch_read": {
+      const message = optionalString(args, "message");
+      if (message !== undefined && messageIdOf(message) === undefined) {
+        problems.push("message must be a full message id (uuid) or a dispatch://KEY/message/<id> reference");
+      }
+      break;
+    }
   }
   return problems;
 }
@@ -16034,6 +16055,9 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, pro
   if (tool === "dispatch_message" && typeof replyTarget === "string" && !replyTarget.startsWith("dispatch://")) {
     return { args, ref, owner: null };
   }
+  if (tool === "dispatch_read" && typeof args.message === "string") {
+    return { args, ref, owner: null };
+  }
   const legionIssue = env.LEGION_ISSUE;
   if (!legionIssue) {
     problems.push(ownerRequiredProblem);
@@ -16953,16 +16977,30 @@ ${followsAsk(askOwner)}`,
       const inReplyTo = messageInReplyTo(args);
       const body = stringArg(args, "body");
       if (owner === null && inReplyTo !== undefined) {
-        const reply = await client.messageReply(inReplyTo, { body, attempt: 1, actor });
+        const reply = await client.messageReply(inReplyTo, { body, attempt: 1, actor }, { followUp: true });
+        if (reply.duplicate === true && reply.body === body) {
+          return {
+            text: `Dispatch already has this exact text in the conversation (message ${reply.id}); ` + "nothing new was posted. Send different text if you have more to say.",
+            details: { message: reply.id, in_reply_to: inReplyTo, posted: false, duplicate: true }
+          };
+        }
         if (reply.body !== body) {
           return {
             text: `Message ${inReplyTo} was already answered by message ${reply.id}; Dispatch kept ` + "that reply and posted nothing. Wait for their next message rather than answering " + "this one again.",
             details: { message: reply.id, in_reply_to: inReplyTo, posted: false }
           };
         }
+        const readBack = `dispatch_read({message: "${inReplyTo}"}) reads the conversation back.`;
+        const parent = reply.in_reply_to ?? undefined;
+        const follows = parent === inReplyTo ? undefined : parent;
         return {
-          text: `Replied to message ${inReplyTo} with message ${reply.id}`,
-          details: { message: reply.id, in_reply_to: inReplyTo, posted: true }
+          text: follows === undefined ? `Replied to message ${inReplyTo} with message ${reply.id}. ${readBack}` : `Replied to message ${inReplyTo} with message ${reply.id}, a follow-up threaded ` + `under your reply ${follows}. ${readBack}`,
+          details: {
+            message: reply.id,
+            in_reply_to: inReplyTo,
+            posted: true,
+            ...follows === undefined ? {} : { follows }
+          }
         };
       }
       const issueKey = issue2();
@@ -17134,6 +17172,21 @@ ${trailer.join(`
       };
     }
     case "dispatch_read": {
+      const message = optionalString(args, "message");
+      if (message !== undefined) {
+        const sessionId = input.sessionId?.trim();
+        if (!sessionId)
+          throw new Error("host session id is required for dispatch_read({message})");
+        const thread = await client.getMessageThread(messageIdOf(message), sessionId);
+        const issueKey2 = thread.message.issue_key;
+        return {
+          text: messageSummary(thread, issueKey2 === null ? [] : await graphSections(client, dispatchChildRef(dispatchIssueRef(issueKey2), "message", thread.message.id))),
+          details: {
+            message: thread.message.id,
+            ...issueKey2 === null ? {} : { issue: issueKey2 }
+          }
+        };
+      }
       if (ownerArguments.ref?.kind === "ask") {
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -894,15 +894,23 @@ dispatch_message({
 
 Leave `issue` out — there is no issue to post into, and naming one would file your answer on
 unrelated work. Dispatch threads the reply under their message in the same conversation, and the
-human sees it on your agent card. Every other message still names its issue, so keep the `issue`
+human sees it in your conversation on the Agents page, where it shows as an unread reply until
+they read it. Every other message still names its issue, so keep the `issue`
 the frame gave you whenever it gave you one; a `dispatch://KEY/message/<id>` reference names the
 issue its message lives on, so that form is a reply on that issue, not a direct message.
 
-One reply per message they send. A second call with the same `in_reply_to` posts nothing:
-Dispatch answers it with the reply already stored, and the tool result says the message was
-already answered rather than reporting a send. That happens most often when your host answered
-the **BTW** automatically before you got here — read the result before writing again, and wait
-for their next message instead.
+Have more to say after you answered? Call it again with the same `in_reply_to` and the new text:
+Dispatch threads that follow-up under your first reply, and the tool result names the reply it
+follows. The same text again posts nothing, so a retry is safe. Your host may already have
+answered a **BTW** automatically before you got here; a second call is then your follow-up to
+that answer, so read the result before writing again.
+
+Read the whole conversation back — their message and every reply, yours included — with the
+message id alone; it has no issue:
+
+```ts
+dispatch_read({ message: "<the direct message's id, or any reply's>" })
+```
 
 ## Following
 

package/skills/legion-worker/SKILL.md

@@ -188,11 +188,17 @@ reviewer, or an architect (in Legion's own deployment, `legion-implementer[bot]`
 check
 `jj -R "$LEGION_WORKSPACE" log -r 'main@origin..@' -T 'author.email() ++ " | " ++ committer.email() ++ " " ++ description.first_line() ++ "\n"'`
 shows your role's App in both columns **on every commit you made** — not on the whole list:
-earlier phases' commits are legitimately authored by their own role's App, and a conflict-forced
-rebase legitimately sets the committer of every rebased commit, other roles' included, to the
-rebaser. A wrong identity on your own commit, the other App or none, is a pane-environment
-problem to report to the architect, not something to pin
-(`docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`, Hazard 1).
+earlier phases' commits are legitimately authored by their own role's App. Their *committer* is
+a different matter, and no longer noise to accept. Resolving a conflict rewrites nothing now —
+it is the forward merge above — so it changes no committer at all, and the one rewrite still
+open to you (*Rewriting pushed commits*, below) resets the committer only of commits on your own
+chain that descend from the commit you named, after its guard cleared. Another role's commit
+carrying you as committer, which you did not rewrite that way, is evidence that something
+rewrote commits it should not have — the observable symptom of LEGION-118. Stop and send the
+architect that log; do not accept it as a side effect. A wrong identity on your own commit, the
+other App or none, is a pane-environment problem to report to the architect, not something to
+pin (`docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`,
+Hazard 1).
 Your session receives the credential capability it needs; invoke GitHub through the
 credential helper:
 
@@ -390,14 +396,17 @@ this proof.
   changes behavior, hides an error, or breaks a gate is fixed here — never deferred.
   Findings about naming, duplication, or wording are batched into the single `Fast-follow`
   line instead of iterating per push.
-- **Rebase only on a real conflict, except after a base retarget.** Sami, 2026-09-11, verbatim:
+- **Reintegrate the base only on a real conflict, except after a base retarget — and with a
+  merge, never `jj rebase`.** Sami, 2026-09-11, verbatim:
   "Please don't do unnecessary rebases (i.e. unless there are merge conflicts). The CI queue is too long and slow."
-  The implementer rebases the issue branch only when GitHub reports it `CONFLICTING`, the controller asks
-  because of a conflict, or after the pull request is retargeted to a new base. Otherwise, never rebase to
+  The implementer merges the base into the issue branch only when GitHub reports it `CONFLICTING`, the controller asks
+  because of a conflict, or after the pull request is retargeted to a new base. Otherwise, never reintegrate the base to
   pick up `main` or refresh CI. A single failed CI job is re-run on its own with `legion gh -- run rerun <run-id> --failed`, never by
   pushing a new commit. A conflict-forced rebase that leaves the branch's diff unchanged is a
-  confirmation, not a new round (see *The unchanged-diff check* below). Before rebasing, record
-  the fingerprint at the current tip; after pushing the rebased branch, record it at the new
+  confirmation, not a new round (see *The unchanged-diff check* below); that name is the event's,
+  kept by the rules below and the learnings that cite it, and the operation it names is always
+  the merge here. Before merging, record
+  the fingerprint at the current tip; after pushing the merged branch, record it at the new
   tip; post one PR comment (Legion footer):
   `rebase <old-tip-sha> → <new-tip-sha>; fingerprint <before> → <after>; unchanged|changed`.
   Every issue workspace is a `jj workspace` of the same shared repository and operation log, and
@@ -646,12 +655,19 @@ remote branch sideways onto your commit and drops theirs (jj 0.45.1:
 push is refused by jj itself (`unexpectedly moved on the remote`).
 
 **Rewriting pushed commits** — a `jj squash --into` a commit already on GitHub, or any other
-rewrite of a commit you already pushed — leaves the pushed tip outside `::@-`, so record
-that tip first, after a fetch and while your chain still descends from it:
+rewrite of a commit you already pushed — is the LEGION-118 hazard in a second shape: jj rebases
+every descendant of any commit it rewrites, and in the one shared repository a descendant can be
+another tree's branch stacked on your pushed commit, which then moves, with its bookmark, onto a
+rewritten copy. So look for a descendant outside your own chain first, and record the pushed tip
+— which the rewrite leaves outside `::@-` — after a fetch and while your chain still descends
+from it:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" git fetch && \
+  foreign=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
+    -r 'descendants(<the commit you are about to rewrite>) ~ ::@') && \
+  { [ -z "$foreign" ] || { echo "not mine, and descends from the commit to rewrite: $foreign" >&2; false; }; } && \
   behind=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
     -r 'remote_bookmarks(exact:"legion/<KEY>", exact:"origin") ~ ::@-') && \
   { [ -z "$behind" ] || { echo "legion/<KEY>@origin is at $behind, which @- does not descend from" >&2; false; }; } && \
@@ -660,6 +676,13 @@ cd -- "$LEGION_WORKSPACE" && \
     >"${TMPDIR:-/tmp}/legion-<KEY>-$LEGION_ROLE-rewritten-tip"
 ```
 
+`descendants(<commit>) ~ ::@` is everything built on the commit you are about to rewrite that is
+not on your own chain. Non-empty means the rewrite would move work that is not yours: do not
+rewrite it. Put the change in a new commit on top instead, and report the listed commits to the
+architect. On a two-workspace rig of this shape a `jj squash --into` a pushed commit reported
+`Rebased 13 descendant commits` and moved a second issue's twelve commits and its bookmark; the
+check above listed those thirteen and refused before anything moved.
+
 Then rewrite, resolve, and push with the procedure above. It lets the remote branch sit on the
 tip you recorded, which the rewrite replaced, and on nothing else: when another role pushed after
 you recorded it, the push is refused. The push deletes the file.