@sjawhar/opencode-legion-envoy 0.41.2 → 0.43.0

package/dist/src/server.js

@@ -13619,6 +13619,8 @@ var CommentEventPayloadSchema = object({
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
   body: string2().optional(),
+  reply_to: string2().nullish(),
+  reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
 var ChildStatusEventPayloadSchema = object({
@@ -13683,15 +13685,17 @@ function dispatchToolSchema(spec, z, opts) {
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue in the repository's dashboard-configured project or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
 var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
-function documentOwnerValidation(requireArtifact) {
+function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
   return {
     check: (value) => {
       const input = value;
       const hasIssue = typeof input.issue === "string";
       const hasProject = typeof input.project === "string";
-      return (hasIssue !== hasProject || !hasIssue && !hasProject && typeof input.ref === "string") && (!hasProject || !requireArtifact || typeof input.artifact === "string");
+      const hasArtifact = typeof input.artifact === "string";
+      const hasRef = typeof input.ref === "string";
+      return (hasIssue !== hasProject || !hasIssue && !hasProject && hasRef) && (!hasProject || !requireArtifact || hasArtifact) && (!alwaysRequireArtifact || hasArtifact || hasRef);
     },
-    message: "Exactly one of issue and project is required; with project, artifact names the document."
+    message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
 var SPEC_SECTIONS = [
@@ -13726,6 +13730,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Project document slug or id.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
@@ -13778,6 +13783,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Artifact slug or id required when quote is given.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
@@ -13792,29 +13798,32 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
-      artifact: z.string().describe("Artifact slug or id containing the quoted text."),
+      artifact: z.string().describe("Artifact slug or id containing the quoted text; optional when ref names it.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z.string().describe("Exact document text to replace."),
       replace_with: z.string().describe("Replacement text."),
       body: z.string({ max: 2000 }).describe("Optional rationale, at most 2,000 characters.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: documentOwnerValidation(true, true)
   },
   {
     name: "dispatch_message",
-    description: "Post a note to the issue's Conversation for humans: a status they should see now, or a reply to a human's message. " + "Not a progress ledger (the issue's progress.md artifact), a decision (dispatch_ask), or document feedback " + `(dispatch_comment). Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    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). Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
-      body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters.")
+      body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
+      reply_to: z.string().describe("Optional message id or dispatch://KEY/message/<id> reference to reply to, threading " + "this message under it so the reply stays with the original in the Conversation.").optional()
     })
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + "dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. The spec (or any document) holds requirements, " + `design, and decisions \u2014 record progress in the issue's progress.md artifact instead. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + "dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. The spec (or any document) holds requirements, " + `design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
-      artifact: z.string().describe("Artifact slug or id for the document."),
+      artifact: z.string().describe("Artifact slug or id for the document; optional when ref names it.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
         find: z.string().describe("Text to find for replace or delete.").optional(),
@@ -13826,7 +13835,7 @@ var dispatchToolSpecs = [
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: documentOwnerValidation(true, true)
   },
   {
     name: "dispatch_doc_read",
@@ -14598,6 +14607,16 @@ class DispatchClient {
   async message(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "messages"], input);
   }
+  async getMessage(issue, id) {
+    return this.#json("GET", [
+      "api",
+      "v1",
+      "issues",
+      await this.#resolveIssue(issue),
+      "messages",
+      id
+    ]);
+  }
   async artifact(issue, input) {
     const artifactPath = ["api", "v1", "issues", await this.#resolveIssue(issue), "artifacts"];
     if ("content" in input)
@@ -14862,10 +14881,10 @@ function parseDispatchRef(ref) {
       id: targetID
     };
   }
-  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+))?$/);
+  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+)|\/message\/([^/]+))?$/);
   if (!issueReference)
     return null;
-  const [, issue, spec, log, children, artifact, version, ask, comment] = issueReference;
+  const [, issue, spec, log, children, artifact, version, ask, comment, message] = issueReference;
   if (!issue || version !== undefined && Number(version) < 1)
     return null;
   const owner = { kind: "issue", issue };
@@ -14887,6 +14906,8 @@ function parseDispatchRef(ref) {
     return { owner, kind: "ask", id: ask };
   if (comment)
     return { owner, kind: "comment", id: comment };
+  if (message)
+    return { owner, kind: "message", id: message };
   return { owner, kind: "issue", id: issue };
 }
 function askId(args) {
@@ -14899,6 +14920,16 @@ function askId(args) {
   }
   return reference.id;
 }
+function messageReplyTo(args) {
+  const replyTo = optionalString(args, "reply_to");
+  if (replyTo === undefined || !replyTo.startsWith("dispatch://"))
+    return replyTo;
+  const reference = parseDispatchRef(replyTo);
+  if (reference?.kind !== "message") {
+    throw new Error("reply_to must be a bare message id or a dispatch://.../message/<id> reference");
+  }
+  return reference.id;
+}
 function toolSchema(tool) {
   const spec = dispatchToolSpecs.find((candidate) => candidate.name === tool);
   if (!spec)
@@ -14910,7 +14941,7 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
-    throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/artifact/<slug>, or dispatch://PROJECT/artifact/<slug>");
+    throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<slug>");
   })() : null;
   const issueArgument = args.issue;
   const projectArgument = args.project;
@@ -15101,6 +15132,18 @@ function commentSummary({ comment, replies }) {
   return ["Comment:", ...root, "Reply chain:", ...chain.length === 0 ? ["- none"] : chain].join(`
 `);
 }
+function messageSummary({ message, replies }) {
+  const root = [
+    `${message.id} \xB7 ${message.author.kind} ${message.author.id}`,
+    `Body: ${message.body}`
+  ];
+  const chain = replies.flatMap((reply) => [
+    `${reply.id} \xB7 ${reply.author.kind} ${reply.author.id}`,
+    `Body: ${reply.body}`
+  ]);
+  return ["Message:", ...root, "Reply chain:", ...chain.length === 0 ? ["- none"] : chain].join(`
+`);
+}
 async function openArtifactMarks(client, resolved) {
   const asks = resolved.owner.kind === "project" ? await client.getArtifactAsks(resolved.artifact.id) : resolved.issue?.open_asks ?? [];
   const marks = asks.filter((ask) => ask.state === "open" && ask.anchor?.artifact_id === resolved.artifact.id).map((ask) => `ask ${ask.id}`);
@@ -15308,9 +15351,15 @@ async function executeDispatchTool(input) {
       };
     }
     case "dispatch_message": {
-      const message = await client.message(issue(), { body: stringArg(args, "body"), actor });
+      const replyTo = messageReplyTo(args);
+      const message = await client.message(issue(), {
+        body: stringArg(args, "body"),
+        ...replyTo === undefined ? {} : { reply_to: replyTo },
+        actor
+      });
+      const messageRef = `dispatch://${message.issue_key}/message/${message.id}`;
       return {
-        text: `Posted message ${message.id}`,
+        text: `Posted message ${message.id} (${messageRef})`,
         details: {
           issue: message.issue_key,
           topic: dispatchIssueSubject(message.issue_key, ">"),
@@ -15397,6 +15446,16 @@ Open anchored asks/comments: ${marks.join(", ")}`,
           details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: comment.comment.issue_key }
         };
       }
+      if (ownerArguments.ref?.kind === "message") {
+        if (ownerArguments.ref.owner.kind !== "issue") {
+          throw new Error("message references are issue-scoped");
+        }
+        const messageRead = await client.getMessage(ownerArguments.ref.owner.issue, ownerArguments.ref.id);
+        return {
+          text: messageSummary(messageRead),
+          details: { issue: messageRead.message.issue_key }
+        };
+      }
       if (documentOwner().kind === "project") {
         const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
         return {

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -5,8 +5,9 @@ description: "Use when asking Sami a question, updating the spec, commenting on
 
 # Dispatch
 
-Dispatch is your issue's or project document's living spec, asks, comments, and artifacts. The transcript is your scratch pad. Anything
-meant for a human goes through a `dispatch_*` tool.
+Dispatch is your issue's or project document's living spec, asks, comments, and artifacts — a high-signal record for the humans who
+decide, never a log of your work. The transcript is your scratch pad; progress and status stay there. Anything meant for a human
+goes through a `dispatch_*` tool.
 
 The server enforces high signal: an ask question is at most 800 characters with at most eight options; comment and message bodies are at
 most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input; it never truncates it. GitHub threads and markers no
@@ -121,8 +122,8 @@ resolved. A human may reply to an open or answered ask; so may you, e.g. after f
 
 The spec holds requirements, design, acceptance, decisions, and rejected alternatives, structured per [Writing a spec](#writing-a-spec).
 It changes only when a decision or requirement changes, and every version that records one is named with `summary`. Never write
-progress, status, timestamps, an "Update HH:MMZ" section, a PR list, or handoff notes into the spec — that belongs in
-[Progress](#progress) instead.
+progress, status, timestamps, an "Update HH:MMZ" section, a PR list, or handoff notes into the spec. Progress is not a
+Dispatch object at all: it lives in your transcript and your pull request (see [Messages](#messages)).
 
 Read the current document before changing it:
 
@@ -163,46 +164,27 @@ and deleting a cell's quoted text removes only that text.
 Use `replace` for inline continuation. 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.
 
-## Progress
-
-Every issue you work has one progress artifact, `progress.md` — for humans reading later and for your own successor after compaction. It
-is never a wake signal.
-
-Create it once, on first use:
-```ts
-dispatch_artifact({ issue, name: "progress.md", content: "### 2026-09-11 15:00Z - Started\n..." })
-```
-The server slugs `progress.md` to `progress-md`; address every later edit with that slug. Append — never edit or remove an earlier
-entry:
-```ts
-dispatch_doc_edit({
-  issue,
-  artifact: "progress-md",
-  ops: [{ op: "insert", after: "end", markdown: "### 2026-09-11 16:10Z - Blocked\n..." }],
-})
-```
-Newest entry last. Each entry is `### <UTC time> - <headline>` followed by 1-5 lines: what changed (cite `dispatch://` refs or PR
-links), what is blocked and on whom, and what is next. `.legion/<phase>.json` is the durable machine handoff between phases;
-`progress.md` is the human-readable narrative for the same work — keep both, never conflate one for the other.
-
 ## Comments and suggestions
 
 Add feedback with:
 
 ```ts
-dispatch_comment({ issue?, project?, artifact?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
+dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
 ```
 
-It returns issue or project-document owner details plus `comment` and, for writes, `topic`. `quote` requires `artifact`; omit both for a
-floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its parent's anchor. Use `reply_to` to
-continue a comment thread at its root; a reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a question
-asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A delivered `comment.created` event carries the
-comment `id`; reply to it with `dispatch_comment({ reply_to: <id> })`.
+It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
+`ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
+`quote` requires `artifact`; omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`)
+takes no `quote`; it belongs to its parent's anchor. Use `reply_to` to continue a comment thread at
+its root; a reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
+question asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A
+delivered `comment.created` event carries the comment `id`; reply to it with
+`dispatch_comment({ reply_to: <id> })`.
 
 Propose an exact replacement instead of describing it:
 
 ```ts
-dispatch_suggest({ issue?, project?, artifact, quote, replace_with, body?, occurrence? })
+dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })
 ```
 
 It returns issue or project-document owner details plus `comment` and its write `topic`. A human accepts or rejects a suggestion.
@@ -230,15 +212,17 @@ or by its filename; the slug also arrives on `artifact.created` events.
 
 ## Messages
 
-Post a note to the issue's Conversation for humans: a short status they should see now (a deploy landed, a blocker appeared), or a reply
-to a human's message.
+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
+"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.
 
 ```ts
 dispatch_message({ issue, body })
 ```
 
-It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. It is not a progress ledger (`progress.md`), a
-decision (`dispatch_ask`), or document feedback (`dispatch_comment`). Your message does not wake anyone unless the issue is routed.
+It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. A message is not a decision
+(`dispatch_ask`) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
 ## What comes back
 
@@ -252,12 +236,17 @@ dispatch_read({ issue?, project?, artifact?, ref? })
 
 With an issue ref, it returns the issue summary, open asks, references, and recent events with `details` `{ issue }`. With a project
 document owner or ref, it returns a document summary with `details` `{ project, document }`. With an ask ref, it returns that ask's
-question, options, state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted reply chain. Reads do
-not subscribe; use `dispatch_doc_read` for document contents.
+question, options, state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted reply chain. With a
+message ref, it returns that message and its reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
 
 ## References
 
-Use these in document, ask, comment, and message bodies; Dispatch unfurls them:
+Use these in document, ask, comment, and message bodies. In the dashboard, a reference renders
+as an inline link whose text is the target's title (an issue's title, an ask's question, a
+comment's first line, a document's name) once it resolves; a body that is only a bare reference
+still gets an unfurl card instead. Every `ref` argument below (and `issue`/`project`) accepts
+either form — an issue key or a project key is never ambiguous, since a project key never
+contains a dash:
 
 ```text
 dispatch://KEY
@@ -265,6 +254,7 @@ dispatch://KEY/spec
 dispatch://KEY/artifact/<slug>[@vN]
 dispatch://KEY/ask/<id>
 dispatch://KEY/comment/<id>
+dispatch://KEY/message/<id>
 dispatch://PROJECT/artifact/<slug>[@vN]
 dispatch://PROJECT/artifact/<slug>/ask/<id>
 dispatch://PROJECT/artifact/<slug>/comment/<id>
@@ -299,27 +289,18 @@ dispatch_ask({
 })
 ```
 
-Before — progress typed once into a message, gone once compaction drops it from context:
+Before — a progress note that nobody needs, posted where humans look for decisions:
 
 ```ts
 dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
 ```
 
-After — append it to the progress artifact, where the record survives:
+After — nothing. The merge is visible on the pull request; the docs work shows up as its own deliverable. Post a message only when
+a human must act or a deliverable is theirs to use:
 
 ```ts
-dispatch_doc_edit({
+dispatch_message({
   issue: "LEGION-815",
-  artifact: "progress-md",
-  ops: [
-    {
-      op: "insert",
-      after: "end",
-      markdown:
-        "### 2026-09-11 15:40Z - Release PR merged\n" +
-        "- dispatch://LEGION-815/artifact/spec stays unchanged; this is progress, not a decision.\n" +
-        "- Next: docs review.",
-    },
-  ],
+  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
 })
 ```

package/skills/legion-architect/SKILL.md

@@ -71,9 +71,9 @@ exercise a criterion end to end, building that path is a child issue of this tre
   inert until released.
 
 Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
-Record ongoing status — wave releases, child closures, blockers — in the issue's `progress.md`
-artifact (see [`skills/dispatch`'s Progress](../dispatch/SKILL.md#progress)), never in the spec
-or a `dispatch_message`.
+Wave releases, child closures, and your own status are visible from the issue tree and the
+handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker only Sami can
+clear is a `dispatch_ask`.
 
 Write one root specification containing the accepted scope, adoption/decomposition,
 waves, acceptance criteria, and integration test. When the config-armed root design gate

package/skills/legion-worker/SKILL.md

@@ -97,9 +97,7 @@ committed predecessor handoffs in lifecycle order from `$LEGION_WORKSPACE/.legio
 Read only files that precede the assigned phase. There is no handoff schema (rejected
 design — no schema validation runs anywhere in this pipeline): write the phase-specific
 fields the next phase and the architect need, consistent with what predecessor phases
-already wrote. The durable copy lives in `$LEGION_WORKSPACE/.legion/<phase>.json` — the machine
-handoff between phases, not a human-readable status; post that to the issue's `progress.md`
-artifact instead (see [`skills/dispatch`'s Progress](../dispatch/SKILL.md#progress)). If a
+already wrote. The durable copy lives in `$LEGION_WORKSPACE/.legion/<phase>.json`. If a
 committed handoff conflicts with memory or a prior transcript, the committed file wins: it
 is the copy that survived.