@sjawhar/opencode-legion-envoy 3.2.4 → 3.2.6

package/dist/src/server.js

@@ -13865,7 +13865,7 @@ function dispatchToolSchema(spec, z2, opts) {
   const schemaOptions = strict === undefined ? undefined : { strict };
   return spec.validation === undefined ? z2.object(shape, schemaOptions) : z2.refineObject(shape, spec.validation.check, spec.validation.message, schemaOptions);
 }
-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 ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference. An external reference addresses an existing Dispatch issue, including one linked to that GitHub pull request; only dispatch_issue with external creates a native issue.";
 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, alwaysRequireArtifact = false) {
   return {
@@ -14005,7 +14005,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_ask",
     example: { issue: "DSP-1", question: "Ship this?" },
-    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
+    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anything you are blocked on a human for, including a credential or grant to renew, an approval, or a decision, is an ask, never a message. " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14126,7 +14126,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, 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). 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, 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}`,
     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."),
@@ -15054,7 +15054,6 @@ class DispatchClient {
   fetchImpl;
   #baseUrl;
   #resolvedIssues = new Map;
-  #creatingIssues = new Map;
   #signal;
   constructor(baseUrl, token, fetchImpl = fetch, signal) {
     this.token = token;
@@ -15065,6 +15064,9 @@ class DispatchClient {
   async issue(input) {
     return this.#json("POST", ["api", "v1", "issues"], input);
   }
+  async resolveIssue(issueReference) {
+    return this.#resolveIssue(issueReference);
+  }
   async listIssues(options = {}) {
     return this.#json("GET", ["api", "v1", "issues"], undefined, options);
   }
@@ -15260,43 +15262,6 @@ class DispatchClient {
       ...query.since === undefined ? {} : { since: query.since }
     });
   }
-  async ensureIssue(issueReference, actor) {
-    if (!issueReference.includes("#"))
-      return issueReference;
-    try {
-      return await this.#resolveIssue(issueReference);
-    } catch (error48) {
-      if (!(error48 instanceof DispatchServiceError) || error48.status !== 404)
-        throw error48;
-    }
-    let creating = this.#creatingIssues.get(issueReference);
-    if (!creating) {
-      creating = this.#createExternalIssue(issueReference, actor);
-      this.#creatingIssues.set(issueReference, creating);
-    }
-    try {
-      return await creating;
-    } finally {
-      if (this.#creatingIssues.get(issueReference) === creating) {
-        this.#creatingIssues.delete(issueReference);
-      }
-    }
-  }
-  async#createExternalIssue(issueReference, actor) {
-    try {
-      const created = await this.#json("POST", ["api", "v1", "issues"], {
-        external: issueReference,
-        actor
-      });
-      this.#resolvedIssues.set(issueReference, Promise.resolve(created.key));
-      return created.key;
-    } catch (error48) {
-      if (error48 instanceof DispatchServiceError && (error48.status === 409 || error48.status === 500)) {
-        return this.#resolveIssue(issueReference);
-      }
-      throw error48;
-    }
-  }
   async#resolveIssue(issueReference) {
     if (!issueReference.includes("#"))
       return issueReference;
@@ -16497,7 +16462,7 @@ async function executeDispatchTool(input) {
   const client = dispatchClient();
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
-    issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
+    issue: await resolveExistingIssue(client, ownerArguments.owner.issue)
   } : ownerArguments.owner;
   const issue2 = () => {
     if (owner?.kind !== "issue")
@@ -17149,13 +17114,12 @@ ${trailer.join(`
       throw new Error(`Unknown Dispatch tool: ${input.tool}`);
   }
 }
-async function ensureIssue(client, issueReference, actor) {
+async function resolveExistingIssue(client, issueReference) {
   try {
-    return await client.ensureIssue(issueReference, actor);
+    return await client.resolveIssue(issueReference);
   } catch (error48) {
-    if (error48 instanceof DispatchServiceError && error48.code === "PROJECT_UNMAPPED") {
-      const repository = issueReference.slice(0, issueReference.lastIndexOf("#"));
-      throw new Error(`repository ${repository} is not mapped in repository settings and no DISPATCH_DEFAULT_PROJECT is configured`);
+    if (error48 instanceof DispatchServiceError && error48.status === 404) {
+      throw new Error(`no Dispatch issue is linked to ${issueReference}; create it first with ` + `dispatch_issue({ external: "${issueReference}", ... })`);
     }
     throw error48;
   }

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -147,8 +147,9 @@ See [Typed blocks](#typed-blocks) for the syntax and [Before you ask](#before-yo
 Every session works on an issue or project document. Legion pre-fills `issue` from `LEGION_ISSUE`: use a native issue key such as
 `LEGION-3`, an external `owner/repo#n` reference, or a bare positive number (resolved against the cwd repository). Otherwise pass
 exactly one owner to every owner-scoped tool: `issue` for an issue, or `project` and `artifact` for an unlinked project document (see
-[References](#references) for the resulting ref shape). On first use, an external issue reference creates its native issue in the
-project configured for that repository in Dispatch Settings, then falls back to `DISPATCH_DEFAULT_PROJECT`.
+[References](#references) for the resulting ref shape). An external issue reference addresses the existing Dispatch issue linked to
+that GitHub issue or pull request. Only `dispatch_issue` with `external` creates a native issue; if no issue is linked, call
+`dispatch_issue({ external: "owner/repo#n", project: "<project>", title: "<title>" })` before addressing it.
 
 Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with neighboring issue keys. They also include nullable coarse priority (`P0` highest through `P3` lowest) and `assignee`: the lowercase GitHub login of the human who answers the issue's asks, or `null` when nobody holds it. `dispatch_read` of an issue prints it as `Assignee: <login>` or `Assignee: unassigned`.
 
@@ -189,8 +190,8 @@ dashboard's **Unclaimed** filter is how you find work nobody is on.
   that session (its id is in the message; `envoy_send` reaches it) or pick up something else,
   and tell the human if you believe the work should be yours. When a **human** holds it, the
   refusal names the person and says nothing about a session running, because there is none to
-  message: ask them on the issue (`dispatch_message`) instead, and never assume their claim has
-  lapsed — only a human releases or forces a human's claim.
+  message: ask them with `dispatch_ask` instead, so the open ask appears in their Inbox, and
+  never assume their claim has lapsed — only a human releases or forces a human's claim.
 - **`409 CLAIM_CONTENDED` means the issue changed hands twice while your call ran**, so nothing
   was applied and nobody's liveness was checked. Read the issue and decide again; it is not a
   refusal by a live holder.
@@ -421,17 +422,16 @@ Before saying you are waiting for human input, call `dispatch_open_asks`. With n
 
 **Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, send a one-line ask before the first implementation commit. A lane's schema decision or a platform-PO contract ruling does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request; it is inferred from AGENTC-186's 2026-09-16 retro (platform PO, 2026-09-17). A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, its options): build it without an ask, as gate 4 of [Before you ask](#before-you-ask) says. This rule covers only product shape outside what he asked for, and its ask comes before the commit that sets that shape.
 
-**Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
-a setting only they can change, a review click, a conflict between two of their own rules - if
-your work waits on it, open a `dispatch_ask` the moment you know, the action as the question. The
-exception is a halt condition from [Before you ask](#before-you-ask) gate 1, which goes to the
-platform PO over Envoy instead.
-Never write it into a spec, a comment reply, a message, or a
-pull-request body: nothing in those paths reaches the human's Inbox, and a human who is not
-reading your document does not know they are the blocker. Before asking, try to remove the
-step: a value already on the machine, a permission you already hold, an API that replaces the
-click. One ask per item, `urgency: "high"` when work is stopped on it; while it is open, keep
-working on everything that is not.
+**Anything you are blocked on a human for is an open ask.** An agent waits on a human only through
+an open ask. An approval, a credential or grant to renew, a setting only they can change, a review
+click, a decision, or a conflict between two of their own rules: open a `dispatch_ask` the moment
+you know, the action as the question. The exception is a halt condition from [Before you
+ask](#before-you-ask) gate 1, which goes to the platform PO over Envoy instead. Never write it
+into a spec, a comment reply, a message, or a pull-request body: nothing in those paths reaches
+the human's Inbox, and a human who is not reading your document does not know they are the
+blocker. Before asking, try to remove the step: a value already on the machine, a permission you
+already hold, an API that replaces the click. One ask per item, `urgency: "high"` when work is
+stopped on it; while it is open, keep working on everything that is not.
 
 A to-do handed to a human is an ordinary question: phrase the to-do as the question and give it
 the options that name its outcomes, in the human's words - there is no fixed vocabulary and the
@@ -724,7 +724,7 @@ 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
-change a human must know about now: a deliverable landed, a blocker only they can clear. Nothing else — no progress updates, no
+change a human must know about now: a deliverable landed. 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.
 

package/skills/legion-controller/SKILL.md

@@ -72,8 +72,8 @@ carries, so nothing changes in how you handle wakes. Under the TypeScript daemon
 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, 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
+Go daemon publishes the rows marked from the Go daemon in 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.
@@ -87,15 +87,29 @@ mints a new secret, so your grants stop working and the role moves to the new se
 
 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.
+hold, a tree architect's failed claim, or a new triage root from while no controller ran never
+arrives as a wake. At every start, before anything else:
+
+1. 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.
+2. List the project's triage issues with `dispatch_issues({project, status: "triage", limit: 250})`.
+   When its first line ends `(showing N of M)`, it is one page: say in your summary how many rows
+   it left unread. The rows show no parent, so open each row with `dispatch_read`: one whose
+   `Links:` name a `child_of` issue is a child, which its parent's architect owns, so leave it,
+   whether or not `legion state --json` records it (a `child_of` under `Referenced by:` is a child
+   of this issue, not its parent). Of the rest, triage each that `legion state --json` does not
+   record under `issues` as a new issue. A root recorded there and now in `triage` is work the
+   daemon holds that a human pulled back: never re-admit it yourself; name it in your summary to
+   the human ("<KEY> was pulled back to triage; what do you want?"). This listing is also the only
+   way you learn of an unrecorded root moved back into triage, or of a child detached to a root
+   while it is in triage, since the daemon wakes you only on a root's creation.
+
+The issue record and Dispatch are the truth; the topic is the wake.
 
 ## Deployment instructions
 
@@ -123,7 +137,7 @@ quoted here.
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
+| New issue created in the Dispatch project (`issue.created`, status `triage`; under the TypeScript daemon resync heals misses, under the Go daemon the boot step above does). From the Go daemon: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for a root only | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
 | Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |

package/skills/legion-worker/SKILL.md

@@ -603,6 +603,11 @@ This publishes your phase's completion to the architect's role and clears the da
 record of this issue's active phase. Do not add pipeline labels, run a controller loop, or
 invent a different completion protocol — this is the whole contract.
 
+A reviewer's phase ends with its completion, not with its review: submit the review on GitHub
+first, then commit the handoff and complete. The daemon moves the issue once both are in — the
+decision GitHub reports and your completion, in either order — so a review posted without a
+completion leaves the issue in reviewing until you finish.
+
 **A refused completion is information, not a retry loop.** The daemon attributes your report to
 the run whose task you took, and answers with what it found. What each answer carries, and what to
 do:
@@ -620,7 +625,10 @@ do:
   has left your phase; report to the architect rather than completing again.
 - `HANDOFF_NO_RUN` — names neither: it says this claim has taken no task, so the daemon cannot
   tell which run you are reporting. Your pane is completing outside any assignment. Say so to the
-  architect; do not re-run the phase.
+  architect; do not re-run the phase. The same answer comes when your turn started before your task
+  reached you: a notice or a message started it, and the task, refused while that turn ran, is sent
+  when the turn ends. When a task arrives, do what it asks; if the work it asks for is already
+  committed, call `handoff_complete` again, and never redo the work or write a second handoff.
 - `HANDOFF_ALREADY_RECORDED` — names your role, the phase, the review round and the commit. This
   exact call was received before, and its first answer stands: accepted, or a refusal the daemon
   records with the call — `HANDOFF_STALE_GENERATION`, `HANDOFF_NOT_CURRENT_PHASE`,