@sjawhar/pi-legion-envoy 5.5.2 → 5.5.4

package/dist/envoy.js

@@ -29960,7 +29960,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 {
@@ -30103,7 +30103,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(),
@@ -30224,7 +30224,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."),
@@ -32265,7 +32265,6 @@ class DispatchClient {
   fetchImpl;
   #baseUrl;
   #resolvedIssues = new Map;
-  #creatingIssues = new Map;
   #signal;
   constructor(baseUrl, token, fetchImpl = fetch, signal) {
     this.token = token;
@@ -32276,6 +32275,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);
   }
@@ -32471,43 +32473,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;
@@ -33685,7 +33650,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")
@@ -34337,13 +34302,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/dist/legion.js

@@ -16142,7 +16142,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.5.2",
+  version: "5.5.4",
   type: "module",
   omp: {
     extensions: [
@@ -30033,7 +30033,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 {
@@ -30176,7 +30176,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(),
@@ -30297,7 +30297,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."),

package/dist/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/dist/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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "5.5.2",
+  "version": "5.5.4",
   "type": "module",
   "omp": {
     "extensions": [