@sjawhar/pi-legion-envoy 1.41.0 → 1.42.1

package/README.md

@@ -85,7 +85,7 @@ extension files it does not contain.
 
 ## Native Dispatch tools
 
-The extension registers seventeen native Dispatch tools: `dispatch_issue`, `dispatch_ask`, `dispatch_edit_ask`,
+The extension registers eighteen native Dispatch tools: `dispatch_issue`, `dispatch_issue_update`, `dispatch_ask`, `dispatch_edit_ask`,
 `dispatch_resolve_ask`, `dispatch_resolve_comment`, `dispatch_follow`, `dispatch_comment`, `dispatch_suggest`,
 `dispatch_message`, `dispatch_doc_edit`, `dispatch_doc_read`, `dispatch_request_approval`, `dispatch_artifact`,
 `dispatch_read`, `dispatch_search`, `dispatch_open_asks`, and `dispatch_whoami`, when Dispatch configuration resolves both a base URL and bearer token.
@@ -112,7 +112,7 @@ whose trimmed contents are the token — how the Legion daemon delivers it to a
 pane) wins over every other token source and never falls back when unreadable.
 Omitting `dispatch.serverUrl` while `dispatch.enabled` is true targets
 `http://localhost:8766`, the Go server's listen address. Invalid configuration,
-an invalid URL, or an empty token leaves the seventeen tools unavailable and
+an invalid URL, or an empty token leaves the eighteen tools unavailable and
 reports the source of the error.
 
 Owner-scoped calls use either an issue (a native `KEY` or external `owner/repo#n` reference) or

package/dist/envoy.js

@@ -29876,6 +29876,17 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
+var ISSUE_STATUSES = [
+  "triage",
+  "icebox",
+  "backlog",
+  "todo",
+  "in_progress",
+  "testing",
+  "needs_review",
+  "retro",
+  "done"
+];
 var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
 var dispatchToolSpecs = [
   {
@@ -29893,6 +29904,26 @@ var dispatchToolSpecs = [
       assignee: z.string().describe("GitHub login of the human who answers this issue's asks; defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional()
     })
   },
+  {
+    name: "dispatch_issue_update",
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), or set its route. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    arguments: (z) => ({
+      issue: z.string().describe(ISSUE_REFERENCE),
+      status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
+      title: z.string({ min: 1 }).describe("Replacement title.").optional(),
+      labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
+      external_links: z.array(z.string({ min: 1 })).describe("URLs to link; merged into the issue's existing external links by URL.").optional(),
+      route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional()
+    }),
+    validation: {
+      check: (value) => {
+        const input = value;
+        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string";
+      },
+      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, or route."
+    },
+    strict: true
+  },
   {
     name: "dispatch_ask",
     description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "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 800 ' + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
@@ -30280,17 +30311,6 @@ var legionRole = _enum2(LEGION_ROLES);
 var requiredUnknown = unknown().refine((value) => value !== undefined, {
   message: "Required"
 });
-var LIFECYCLE_STATUSES = [
-  "triage",
-  "icebox",
-  "backlog",
-  "todo",
-  "in_progress",
-  "testing",
-  "needs_review",
-  "retro",
-  "done"
-];
 var architectCapability = strictObject({
   tree: nonEmptyString,
   sessionId: nonEmptyString,
@@ -30322,7 +30342,7 @@ var stateTreeLocator = discriminatedUnion("runtime", [
 var stateIssue = strictObject({
   key: nonEmptyString,
   title: string2(),
-  status: _enum2(LIFECYCLE_STATUSES).optional(),
+  status: _enum2(ISSUE_STATUSES).optional(),
   children: array(nonEmptyString),
   parent: nonEmptyString.optional(),
   lastAppliedSeq: number2().int().nonnegative().optional()
@@ -30491,7 +30511,7 @@ var LegionDaemonApi = {
   },
   IssueStatus: {
     request: controllerIssue.extend({
-      status: _enum2(LIFECYCLE_STATUSES),
+      status: _enum2(ISSUE_STATUSES),
       tree: nonEmptyString.optional(),
       sessionId: nonEmptyString.optional()
     }),
@@ -31862,6 +31882,9 @@ class DispatchClient {
   async getIssue(issue) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue)]);
   }
+  async updateIssue(issue, input) {
+    return this.#json("PATCH", ["api", "v1", "issues", await this.#resolveIssue(issue)], input);
+  }
   async getIssueEvents(issue, after = 0, limit = 200) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "events"], undefined, { after, limit });
   }
@@ -33043,6 +33066,51 @@ async function executeDispatchTool(input) {
         };
       }
     }
+    case "dispatch_issue_update": {
+      const issueKey = issue();
+      const status = optionalString(args, "status");
+      const title = optionalString(args, "title");
+      const route = optionalString(args, "route");
+      const labels = Array.isArray(args.labels) ? args.labels : undefined;
+      const requestedLinks = Array.isArray(args.external_links) ? [...new Set(args.external_links)] : undefined;
+      let newLinks = [];
+      try {
+        const before = await client.getIssue(issueKey);
+        const linked = before.external_links.map((link) => link.url);
+        newLinks = requestedLinks?.filter((url) => !linked.includes(url)) ?? [];
+        const after = await client.updateIssue(issueKey, {
+          ...status === undefined ? {} : { status },
+          ...title === undefined ? {} : { title },
+          ...labels === undefined ? {} : { labels },
+          ...route === undefined ? {} : { route },
+          ...requestedLinks === undefined ? {} : { external_links: [...before.external_links, ...newLinks.map((url) => ({ url }))] },
+          actor
+        });
+        const linkCount = `(${after.external_links.length} ${after.external_links.length === 1 ? "link" : "links"})`;
+        const changes = [
+          ...status === undefined ? [] : [`status ${before.status} -> ${after.status}`],
+          ...title === undefined ? [] : [`title "${after.title}"`],
+          ...labels === undefined ? [] : [after.labels.length === 0 ? "labels cleared" : `labels ${after.labels.join(", ")}`],
+          ...requestedLinks === undefined ? [] : [
+            newLinks.length === 0 ? `already linked ${requestedLinks.join(", ")} ${linkCount}` : `linked ${newLinks.join(", ")} ${linkCount}`
+          ],
+          ...route === undefined ? [] : [after.route === null ? "route cleared" : `route ${after.route}`]
+        ];
+        return {
+          text: `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
+          details: {
+            issue: after.key,
+            status: after.status,
+            external_links: after.external_links.map((link) => link.url)
+          }
+        };
+      } catch (error) {
+        if (!(error instanceof DispatchServiceError))
+          throw error;
+        const taken = error.status === 500 && newLinks.length > 0 ? `; one of ${newLinks.join(", ")} may already be linked from another issue (a URL links exactly one issue)` : "";
+        throw new DispatchServiceError(error.code, error.status, `${error.code}: ${error.message}${taken}`, error.candidates);
+      }
+    }
     case "dispatch_search": {
       const query = stringArg(args, "query");
       const project = optionalString(args, "project");

package/dist/legion.js

@@ -29150,6 +29150,17 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
+var ISSUE_STATUSES = [
+  "triage",
+  "icebox",
+  "backlog",
+  "todo",
+  "in_progress",
+  "testing",
+  "needs_review",
+  "retro",
+  "done"
+];
 var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
 var dispatchToolSpecs = [
   {
@@ -29167,6 +29178,26 @@ var dispatchToolSpecs = [
       assignee: z.string().describe("GitHub login of the human who answers this issue's asks; defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional()
     })
   },
+  {
+    name: "dispatch_issue_update",
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), or set its route. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    arguments: (z) => ({
+      issue: z.string().describe(ISSUE_REFERENCE),
+      status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
+      title: z.string({ min: 1 }).describe("Replacement title.").optional(),
+      labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
+      external_links: z.array(z.string({ min: 1 })).describe("URLs to link; merged into the issue's existing external links by URL.").optional(),
+      route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional()
+    }),
+    validation: {
+      check: (value) => {
+        const input = value;
+        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string";
+      },
+      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, or route."
+    },
+    strict: true
+  },
   {
     name: "dispatch_ask",
     description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "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 800 ' + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
@@ -29554,17 +29585,6 @@ var legionRole = _enum2(LEGION_ROLES);
 var requiredUnknown = unknown().refine((value) => value !== undefined, {
   message: "Required"
 });
-var LIFECYCLE_STATUSES = [
-  "triage",
-  "icebox",
-  "backlog",
-  "todo",
-  "in_progress",
-  "testing",
-  "needs_review",
-  "retro",
-  "done"
-];
 var architectCapability = strictObject({
   tree: nonEmptyString,
   sessionId: nonEmptyString,
@@ -29596,7 +29616,7 @@ var stateTreeLocator = discriminatedUnion("runtime", [
 var stateIssue = strictObject({
   key: nonEmptyString,
   title: string2(),
-  status: _enum2(LIFECYCLE_STATUSES).optional(),
+  status: _enum2(ISSUE_STATUSES).optional(),
   children: array(nonEmptyString),
   parent: nonEmptyString.optional(),
   lastAppliedSeq: number2().int().nonnegative().optional()
@@ -29765,7 +29785,7 @@ var LegionDaemonApi = {
   },
   IssueStatus: {
     request: controllerIssue.extend({
-      status: _enum2(LIFECYCLE_STATUSES),
+      status: _enum2(ISSUE_STATUSES),
       tree: nonEmptyString.optional(),
       sessionId: nonEmptyString.optional()
     }),
@@ -30294,19 +30314,8 @@ function toolFailure(error) {
 
 // src/legion/tools.ts
 var jsonSuccess = (details) => toolSuccess(JSON.stringify(details), details);
-var LIFECYCLE_STATUSES2 = [
-  "triage",
-  "icebox",
-  "backlog",
-  "todo",
-  "in_progress",
-  "testing",
-  "needs_review",
-  "retro",
-  "done"
-];
-function isLifecycleStatus(value) {
-  return LIFECYCLE_STATUSES2.includes(value);
+function isIssueStatus(value) {
+  return ISSUE_STATUSES.includes(value);
 }
 function isDispatchArtifactId(value) {
   return LegionDaemonApi.GatesRegister.request.shape.artifactId.safeParse(value).success;
@@ -30323,7 +30332,7 @@ function legionToolSchema(pi) {
   return z.object({
     op: z.enum(["set_status", "register_gate", "release_wave", "escalate", "spawn_worker"]),
     issue: z.string().optional(),
-    status: z.enum(LIFECYCLE_STATUSES2).optional(),
+    status: z.enum(ISSUE_STATUSES).optional(),
     artifactId: z.string().optional(),
     version: z.number().optional(),
     kind: z.enum(["re-file", "capacity", "cross-tree"]).optional(),
@@ -30365,7 +30374,7 @@ function createLegionTool(deps) {
         switch (parameters.op) {
           case "set_status": {
             const status = parameters.status;
-            if (typeof status !== "string" || !isLifecycleStatus(status)) {
+            if (typeof status !== "string" || !isIssueStatus(status)) {
               throw new Error("set_status requires a valid Legion issue status");
             }
             await daemon.issueStatus({

package/dist/skills/dispatch/SKILL.md

@@ -108,6 +108,29 @@ dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: str
 `details` `{ issue }`; creating an issue does not subscribe you to it (see [Following](#following)). Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is supplied,
 follow [Writing a spec](#writing-a-spec).
 
+## Issue status is yours to move
+
+The issue's status is how a human sees delivery without asking a session. Outside Legion (where
+the daemon writes it), the session doing the work moves it, the way a person moves a card:
+`in_progress` when implementation starts, `testing` when the change is being proven on a
+production-like surface, `needs_review` when its pull request is open and waiting on the merge
+queue, `done` when the change has been driven in production (a merge is not `done`). Move child
+issues you own as well as the root. An issue left at `triage` while work is underway is a defect:
+Sami, 2026-09-15, on the roadmap he could not read — "I'm not even sure what their development
+status is." Waiting for the deploy lane is not a status and is never announced. Priority stays the
+human's: set it on creation only when their intent is clear, and change it only on their word.
+
+```ts
+// PATCH /api/v1/issues/{key} — status, title, labels, external_links (merged by URL), route
+dispatch_issue_update({ issue: "AGENTC-175", status: "testing" })
+dispatch_issue_update({ issue: "AGENTC-175", external_links: ["https://github.com/owner/repo/pull/7"] })
+```
+
+Link the pull request that delivers the issue in `external_links` when you open it; the issue page
+renders its state and checks from that link. The call is authenticated with the same bearer as every
+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`.
+
 ## Search first
 
 Before you create an issue or start a design document, search:
@@ -462,7 +485,10 @@ dispatch_message({
 
 `in_reply_to` correlates the answer under the asker's message in its Conversation card. A BTW
 delivery can post its answer automatically; use this call when the frame asks the primary agent to
-reply. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
+reply. A human may reply to your message in turn — the follow-up arrives as a targeted frame whose
+`in_reply_to` names your message and whose `reply_body` quotes it; answer it the same way,
+`dispatch_message({ issue, in_reply_to: "<their reply id>", body })`, so the exchange reads as one
+thread. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
 through Envoy or the hub. A bearer that targets over HTTP names its own session in `actor`
 (`{kind: "session", id}`), and the card shows that session as the author. `GET /api/v1/agents`
 (any authenticated caller) lists live sessions with their capabilities (`aside`, `btw`, `steer`);

package/package.json

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