@sjawhar/opencode-legion-envoy 1.44.0 → 1.45.1

package/dist/src/server.js

@@ -15436,6 +15436,36 @@ function notSubscribed(owner) {
 function followsAsk(owner) {
   return `You follow this ask: its answer and replies reach you directly. For every event on ${owner.label}: envoy_subscribe ${owner.topic}`;
 }
+var triageAdviceShown = new Set;
+function renderAdvice(tool, key, advice, opts) {
+  if (advice === undefined)
+    return [];
+  const hasIssueAdvice = advice.issue_status !== undefined;
+  const openAsks = advice.your_open_asks;
+  const writesSinceHuman = advice.session_writes_since_human;
+  const lines = [];
+  if (advice.decision_blocks === 0 && opts.isPrimarySpec === true && (tool === "dispatch_issue" || tool === "dispatch_artifact")) {
+    lines.push('No decision blocks in this spec \u2014 nothing here reaches a human\'s inbox. Want human feedback? See the `dispatch` skill, "Decision blocks".');
+  }
+  if (hasIssueAdvice && writesSinceHuman !== undefined && writesSinceHuman >= 3 && (tool === "dispatch_message" || tool === "dispatch_ask" || tool === "dispatch_comment" && opts.isAskReply !== true)) {
+    const middle = writesSinceHuman >= 6 ? "Stop posting here until a human replies." : "Progress ledger or scratchpad? If so, stop.";
+    lines.push(`You've sent ${writesSinceHuman} messages on ${key} with no human response. ${middle} See the \`dispatch\` skill, "Structure over stream".`);
+  }
+  if (advice.issue_status === "triage" && tool !== "dispatch_issue" && !(tool === "dispatch_issue_update" && opts.setsStatus === true) && !triageAdviceShown.has(key)) {
+    triageAdviceShown.add(key);
+    lines.push(`${key} is still in triage \u2014 nobody can see its development status. See the \`dispatch\` skill, "Issue status is yours to move".`);
+  }
+  if (hasIssueAdvice && openAsks !== undefined && openAsks.length > 0 && (tool === "dispatch_message" || tool === "dispatch_doc_edit" || tool === "dispatch_issue_update" || tool === "dispatch_comment" && opts.replyToOwnAsk !== true)) {
+    const askCount = Math.min(openAsks.length, 2);
+    for (let index = 0;index < askCount; index += 1) {
+      const ask = openAsks[index];
+      if (ask === undefined)
+        break;
+      lines.push(`You still have an open ask on ${key}: "${ask.question.slice(0, 80)}" (${ask.id}). Still needed? See the \`dispatch\` skill, "Close what you opened".`);
+    }
+  }
+  return lines;
+}
 function documentResultDetails(artifact) {
   return {
     project: artifact.project,
@@ -16324,9 +16354,19 @@ async function executeDispatchTool(input) {
           ...Array.isArray(labels) ? { labels } : {},
           actor
         });
+        const adviceLines = renderAdvice(input.tool, created.key, created.advice, {
+          isPrimarySpec: spec !== undefined
+        });
         return {
-          text: `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
-          details: { issue: created.key }
+          text: [
+            `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
+            ...adviceLines
+          ].join(`
+`),
+          details: {
+            issue: created.key,
+            ...created.advice === undefined ? {} : { advice: created.advice }
+          }
         };
       } catch (error) {
         if (!(error instanceof DispatchServiceError) || error.code !== "POSSIBLE_DUPLICATE") {
@@ -16383,12 +16423,20 @@ async function executeDispatchTool(input) {
           ...parent === undefined ? [] : [after.parent === null ? "parent cleared" : `parent -> ${after.parent}`],
           ...components === undefined ? [] : [componentsChange(components, after.components)]
         ];
+        const adviceLines = renderAdvice(input.tool, after.key, after.advice, {
+          setsStatus: status !== undefined
+        });
         return {
-          text: `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
+          text: [
+            `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
+            ...adviceLines
+          ].join(`
+`),
           details: {
             issue: after.key,
             status: after.status,
-            external_links: after.external_links.map((link) => link.url)
+            external_links: after.external_links.map((link) => link.url),
+            ...after.advice === undefined ? {} : { advice: after.advice }
           }
         };
       } catch (error) {
@@ -16519,10 +16567,18 @@ async function executeDispatchTool(input) {
       };
       const ask = resolved?.owner.kind === "project" ? await client.artifactAsk(resolved.artifact.id, askInput) : await client.ask(issue(), askInput);
       const askOwner = ask.issue_key !== null ? issueTopic(ask.issue_key) : resolved === undefined ? issueTopic(issue()) : documentTopic(resolved.artifact);
+      const adviceLines = renderAdvice(input.tool, askOwner.label, ask.advice, {});
       return {
-        text: `Asked ${ask.id} on ${askOwner.label} (urgency ${ask.urgency}): ${ask.question}
+        text: [
+          `Asked ${ask.id} on ${askOwner.label} (urgency ${ask.urgency}): ${ask.question}
 ${followsAsk(askOwner)}`,
-        details: await followedAskDetails(client, ask, resolved?.artifact)
+          ...adviceLines
+        ].join(`
+`),
+        details: {
+          ...await followedAskDetails(client, ask, resolved?.artifact),
+          ...ask.advice === undefined ? {} : { advice: ask.advice }
+        }
       };
     }
     case "dispatch_edit_ask": {
@@ -16567,21 +16623,34 @@ ${followsAsk(askOwner)}`,
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
       const commentOwner = resolved === undefined ? issueTopic(issue()) : resolvedTopic(resolved);
       const commentDetails = resolved === undefined ? { issue: comment.issue_key, comment: comment.id } : writeResultDetails(resolved, { comment: comment.id });
+      const adviceLines = renderAdvice(input.tool, commentOwner.label, comment.advice, {
+        isAskReply: replyToAsk !== undefined,
+        replyToOwnAsk: replyToAsk !== undefined && (comment.advice?.your_open_asks?.some((ask) => ask.id === replyToAsk) ?? false)
+      });
       if (replyToAsk !== undefined) {
         const askState = comment.turn === null ? "" : `; ask now waiting on ${comment.turn}`;
         return {
-          text: `Replied on ask ${replyToAsk} (comment ${comment.id}${askState}). ${followsAsk(commentOwner)}`,
+          text: [
+            `Replied on ask ${replyToAsk} (comment ${comment.id}${askState}). ${followsAsk(commentOwner)}`,
+            ...adviceLines
+          ].join(`
+`),
           details: {
             ...commentDetails,
             ask: replyToAsk,
             follows: { ask: replyToAsk },
-            ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+            ...comment.turn === null ? {} : { ask_waiting_on: comment.turn },
+            ...comment.advice === undefined ? {} : { advice: comment.advice }
           }
         };
       }
       return {
-        text: `Posted comment ${comment.id} ${notSubscribed(commentOwner)}`,
-        details: commentDetails
+        text: [`Posted comment ${comment.id} ${notSubscribed(commentOwner)}`, ...adviceLines].join(`
+`),
+        details: {
+          ...commentDetails,
+          ...comment.advice === undefined ? {} : { advice: comment.advice }
+        }
       };
     }
     case "dispatch_suggest": {
@@ -16611,9 +16680,18 @@ ${followsAsk(askOwner)}`,
         actor
       });
       const messageRef = dispatchChildRef(dispatchIssueRef(issueKey), "message", message.id);
+      const adviceLines = renderAdvice(input.tool, issueKey, message.advice, {});
       return {
-        text: `Posted message ${message.id} (${messageRef}) ${notSubscribed(issueTopic(issueKey))}`,
-        details: { issue: issueKey, message: message.id }
+        text: [
+          `Posted message ${message.id} (${messageRef}) ${notSubscribed(issueTopic(issueKey))}`,
+          ...adviceLines
+        ].join(`
+`),
+        details: {
+          issue: issueKey,
+          message: message.id,
+          ...message.advice === undefined ? {} : { advice: message.advice }
+        }
       };
     }
     case "dispatch_doc_edit": {
@@ -16631,11 +16709,14 @@ ${followsAsk(askOwner)}`,
       const retyped = ops.filter((operation) => operation.op === "retype").length;
       const versionText = edited.version === null ? "no new version" : `version ${edited.version.number}`;
       const applied = retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`;
+      const adviceLines = renderAdvice(input.tool, resolvedTopic(resolved).label, edited.advice, {});
       return {
-        text: `${applied} ${notSubscribed(resolvedTopic(resolved))}`,
+        text: [`${applied} ${notSubscribed(resolvedTopic(resolved))}`, ...adviceLines].join(`
+`),
         details: writeResultDetails(resolved, {
           applied: edited.applied,
-          ...edited.version === null ? {} : { version: edited.version.number }
+          ...edited.version === null ? {} : { version: edited.version.number },
+          ...edited.advice === undefined ? {} : { advice: edited.advice }
         })
       };
     }
@@ -16707,15 +16788,24 @@ ${trailer.join(`
       const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
       const artifactRef = dispatchDocumentRef(artifactOwner.kind === "project" ? artifactOwner.project : issue(), result.artifact.slug);
       const uploadOwner = artifactOwner.kind === "project" ? documentTopic(result.artifact) : issueTopic(issue());
+      const adviceLines = renderAdvice(input.tool, uploadOwner.label, result.advice, {
+        isPrimarySpec: result.artifact.primary || result.artifact.name === "spec.md"
+      });
       return {
-        text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef}) ${notSubscribed(uploadOwner)}`,
+        text: [
+          `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef}) ${notSubscribed(uploadOwner)}`,
+          ...adviceLines
+        ].join(`
+`),
         details: artifactOwner.kind === "project" ? {
           ...documentResultDetails(result.artifact),
-          version: result.version.number
+          version: result.version.number,
+          ...result.advice === undefined ? {} : { advice: result.advice }
         } : {
           issue: issue(),
           artifact: result.artifact.id,
-          version: result.version.number
+          version: result.version.number,
+          ...result.advice === undefined ? {} : { advice: result.advice }
         }
       };
     }

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch
-description: "Use when asking Sami a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
+description: "Use before posting a message, a status update, or a periodic status update; before asking a question that references another message, artifact, or eval; and when asking Sami a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
 ---
 
 # Dispatch
@@ -75,13 +75,11 @@ route"}`; when you see that, you typed the path wrong — read the index rather
 
 ## Writing a spec
 
-A spec has two readers: the human who decides reads the top; the implementer who builds reads the
-rest. Use these headings in this order.
+A spec has two readers: the human who decides reads the **Summary** and **New since we talked** at the top, then each decision through its [`:::ask` block](#decision-blocks) where it arises; the implementer who builds reads the rest. Use these headings in this order.
 
 | Section | Required content | Form |
 | --- | --- | --- |
 | **Summary** | The problem, what changes for whom, and how we will know it worked — in plain words. | Three sentences at most. |
-| **Decisions needed** | Only decisions that need human authority, taste, or risk appetite: each one plain question, two or three options with what each costs, and your recommendation with its reason — written as an `ask` block directly under those options, so it is answered in context (see [Design changes are brainstormed here](#design-changes-are-brainstormed-here)). An answered item moves into Requirements with its provenance. | One `ask` block per decision; empty is fine. |
 | **New since we talked** | Every design point the human did not settle in conversation, marked `inferred:` with the reasoning. Empty is fine. | One plain sentence per point. |
 | **Acceptance** | Each outcome names what a user will observe and the check that proves it (browser scenario, API call, or command). An outcome without a check is not acceptance. | Numbered lines. |
 | **Requirements** | What must hold, and where each came from: a quoted human sentence, or `inferred:` plus the reasoning. Readers treat inferred requirements as hypotheses. | `requirement \| where it comes from` table, or prose if the reader follows it more easily. |
@@ -94,13 +92,33 @@ rest. Use these headings in this order.
 
 - The spec is the issue's one primary document. Extend it in place — a new version that keeps the
   human's own text — never a second "spec" artifact beside it.
-- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is either a
-  Decision needed or a question for the platform PO whose ruling becomes a Requirement (see
+- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is either
+  an ask block or a question for the platform PO whose ruling becomes a Requirement (see
   [Before you ask](#before-you-ask) under Asking).
 - Keep each section to one screen; work that exceeds one screen per section is two specs.
 - Update the spec as decisions land: the spec is the record, comments are the discussion.
 - Before sending it: no sections conflict, every requirement has exactly one reading, and the
-  Summary and Decisions pass the phone test above.
+  Summary and every ask block pass the phone test above.
+
+## Decision blocks
+
+A decision a human must make is an `:::ask` block where the decision arises in the spec: inside
+the section whose content it is about, never gathered into a list at the top or bottom. Sami,
+LEGION-204 comment, 2026-09-20 14:47Z, verbatim: "Adding a bunch of decision blocks at the top is
+terrible!! Decisions should be in context in the spec".
+
+The block is what reaches the human's Inbox. A question phrased as prose in the spec reaches
+nobody. A spec with no ask blocks is fine only when the issue genuinely needs no human decision.
+When `dispatch_issue` or `dispatch_artifact` answers `No decision blocks in this spec …`, read it
+as a question, not an error: either no decision is needed and you say nothing, or you forgot to
+make the decision a block and must fix the spec.
+
+**Wrong:** a **Decisions needed** list at the top of the spec with three bullets.
+**Right:** put each decision in the design section it belongs to as an `:::ask{#slug}` block, with
+2–4 options, a recommendation, and surrounding prose that explains the trade-off.
+
+See [Typed blocks](#typed-blocks) for the syntax and [Before you ask](#before-you-ask) under
+[Asking](#asking) to decide whether the question is a real decision at all.
 
 ## Your owner
 
@@ -152,6 +170,9 @@ renders its state and checks from that link. The call is authenticated with the
 other `dispatch_*` tool: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
 the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
 
+A write to an issue still in `triage` answers once with `… is still in triage …`; move the status
+when work has started.
+
 ## Search first
 
 Before you create an issue or start a design document, search:
@@ -353,6 +374,26 @@ yet — "dispatched two auditors, back with results", "checking the release bran
 turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
 `ask_waiting_on`, and every ask read carries it as `waiting_on`.
 
+## Close what you opened
+
+An ask you opened is yours until it is answered or you resolve it. When the answer arrives some
+other way — Sami said it live, a later comment settled it, or the question became moot because the
+design moved — resolve it yourself with `dispatch_resolve_ask` in the same turn you learn that.
+Never leave it for the human to clear.
+
+Sami, AGENTC-27 `rules-derivation-2026-09-17.md` row R04, verbatim: "I think this was answered
+live. If not, please reask." The same pattern left him closing asks as `Dismissed`, `Settled`, and
+`Resolved I think`: noise the human had to clear.
+
+Every later write on the issue answers `You still have an open ask on …` and names it. Treat that
+as the checklist: if it is still needed, leave it; if it was answered elsewhere, resolve it with
+the resolving fact as the reason. Before posting a new ask, inspect your open ones. If the new ask
+supersedes one, retract the old one with `dispatch_resolve_ask` and kind `retracted` in the same
+turn.
+
+See [Following](#following) for why you receive what happens to asks you open and
+[What comes back](#what-comes-back) for finding them again with `dispatch_open_asks`.
+
 ## Approval of a spec
 
 Approval is a property of a document, not a question you phrase: a human approves a specific version, the way a pull-request
@@ -592,6 +633,10 @@ high-signal, structured conversation"). The structure IS the product:
 - **Never split one deliverable across a message + an ask that points at it.** Ask the question
   with the document reference in the question text; the reader lands on the content in one click.
 
+The tool result answers your third consecutive message on an issue with no human reply with
+`You've sent N messages …`. That is the ledger pattern being named; stop and either wait or ask
+once.
+
 ## Messages
 
 Dispatch is a high-signal record for humans, not a log of what you are doing. A message is a reply to a human's message, or a
@@ -678,6 +723,8 @@ title is invisible to the graph.
 
 ## References
 
+**Every reference is a link, never an unlinked mention.** If you name a thing that has an address, link it: another issue, ask, comment, spec, or message (the `dispatch://` forms below), an artifact (`dispatch://KEY/artifact/<slug>`), an eval (its viewer URL), a Slack message (its permalink), a Drive file (its share link). Bare phrases like "see this eval", "his 09-04 run", "the comment above", or "per the spec" with no link are banned: they make the reader hunt for what you already had in hand, and nothing can be traversed from them. Linking every reference is what makes a body both consumable and navigable. If a thing genuinely has no linkable address, say so; otherwise the link is not optional.
+
 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