@sjawhar/opencode-legion-envoy 1.29.1 → 1.31.0

package/README.md

@@ -13,6 +13,7 @@ This package exposes:
 - `envoy_whoami`
 - `envoy_sessions`
 - `dispatch_issue`
+- `dispatch_issue_update`
 - `dispatch_ask`
 - `dispatch_edit_ask`
 - `dispatch_resolve_ask`
@@ -28,8 +29,9 @@ This package exposes:
 - `dispatch_read`
 - `dispatch_search`
 - `dispatch_open_asks`
+- `dispatch_whoami`
 
-The sixteen native `dispatch_*` tools create and read Dispatch issues, asks, comments,
+The eighteen native `dispatch_*` tools create and read Dispatch issues, asks, comments,
 documents, and artifacts, or search all of them. They are present when `dispatch.enabled`
 resolves a server URL and bearer token from envoy.json (`~/.config/opencode/envoy.json`, merged
 with `<repo>/.opencode/envoy.json`) or the `DISPATCH_URL` and `DISPATCH_TOKEN` environment

package/dist/src/server.js

@@ -13779,6 +13779,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 = [
   {
@@ -13792,9 +13803,30 @@ var dispatchToolSpecs = [
       force: z.boolean().describe("Create even though POSSIBLE_DUPLICATE listed similar issues; pass it only after reading them.").optional(),
       spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional(),
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional(),
-      priority: z.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional()
+      priority: z.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional(),
+      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}`,
@@ -13997,6 +14029,12 @@ var dispatchToolSpecs = [
     description: "List this session's active unanswered asks across issues and project documents, including age and whose reply is needed. Call before saying you are waiting for human input.",
     arguments: () => ({}),
     strict: true
+  },
+  {
+    name: "dispatch_whoami",
+    description: "Who Dispatch takes this session for: {session, owner}. owner is the lowercase GitHub login of the human whose personal token you run under (the default assignee of issues you create), or null under the shared token.",
+    arguments: () => ({}),
+    strict: true
   }
 ];
 // ../contracts/src/envelope.ts
@@ -14159,17 +14197,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,
@@ -14201,7 +14228,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()
@@ -14370,7 +14397,7 @@ var LegionDaemonApi = {
   },
   IssueStatus: {
     request: controllerIssue.extend({
-      status: _enum2(LIFECYCLE_STATUSES),
+      status: _enum2(ISSUE_STATUSES),
       tree: nonEmptyString.optional(),
       sessionId: nonEmptyString.optional()
     }),
@@ -14792,6 +14819,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 });
   }
@@ -14810,6 +14840,9 @@ class DispatchClient {
       ...since === undefined ? {} : { since }
     });
   }
+  async whoami() {
+    return this.#json("GET", ["api", "v1", "whoami"]);
+  }
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
@@ -15223,7 +15256,8 @@ var issueFreeTools = {
   dispatch_resolve_comment: true,
   dispatch_follow: true,
   dispatch_search: true,
-  dispatch_open_asks: true
+  dispatch_open_asks: true,
+  dispatch_whoami: true
 };
 function canonicalExternalIssueRef(value) {
   const match = value.trim().match(externalIssueRefPattern);
@@ -15639,10 +15673,13 @@ function issueSummary(issue, events, references, graph) {
   const specApproval = spec === undefined ? undefined : approvalLine(spec);
   if (issue.priority === undefined)
     throw new Error("Dispatch issue is missing priority");
+  if (issue.assignee === undefined)
+    throw new Error("Dispatch issue is missing assignee");
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
+    `Assignee: ${issue.assignee ?? "unassigned"}`,
     ...issue.priority === null ? [] : [`Priority: P${issue.priority}`],
     `Labels: ${issue.labels.length === 0 ? "none" : issue.labels.join(", ")}`,
     `Route: ${issue.route ?? "none"}`,
@@ -15890,6 +15927,18 @@ async function executeDispatchTool(input) {
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
+  if (input.tool === "dispatch_whoami") {
+    const sessionId = input.sessionId?.trim();
+    if (!sessionId)
+      throw new Error("host session id is required for dispatch_whoami");
+    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const identity = await client.whoami();
+    const owner = identity.kind === "agent" ? identity.owner : identity.login.toLowerCase();
+    return {
+      text: owner === null ? `Session ${sessionId} runs under the shared token: no owner, so issues you create without an assignee are unassigned (or inherit their parent's).` : `Session ${sessionId} acts for ${owner}: issues you create without an assignee are assigned to ${owner}.`,
+      details: { session: sessionId, owner }
+    };
+  }
   const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
@@ -15916,6 +15965,7 @@ async function executeDispatchTool(input) {
       const force = optionalBoolean(args, "force");
       const spec = optionalString(args, "spec");
       const priority = optionalNumber(args, "priority");
+      const assignee = optionalString(args, "assignee");
       const labels = args.labels;
       try {
         const created = await client.issue({
@@ -15926,6 +15976,7 @@ async function executeDispatchTool(input) {
           ...force === undefined ? {} : { force },
           ...spec === undefined ? {} : { spec },
           ...priority === undefined ? {} : { priority },
+          ...assignee === undefined ? {} : { assignee },
           ...Array.isArray(labels) ? { labels } : {},
           actor
         });
@@ -15952,6 +16003,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/package.json

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

package/skills/dispatch/SKILL.md

@@ -90,16 +90,47 @@ exactly one owner to every owner-scoped tool: `issue` for an issue, or `project`
 [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`.
 
-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).
+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`.
+
+### Who answers an ask
+
+An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with:
+```ts
+dispatch_whoami({})
+```
+It returns `details` `{ session, owner }`: `owner` is the lowercase login of the human whose personal token you run under, or `null` under the shared token. An issue you create without `assignee` goes to your owner; under the shared token it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<login>"}`; any authenticated caller may reassign, and an unlisted login is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
 
 Architects create newly tracked child work with:
 ```ts
-dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3 })
+dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3, assignee?: string })
 ```
-`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. Set `priority` on creation only when the human's intent makes the bucket clear; otherwise priority remains the human's decision. It returns
+`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. Set `priority` on creation only when the human's intent makes the bucket clear; otherwise priority remains the human's decision. Set `assignee` (a GitHub login on the sign-in allowlist) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It returns
 `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:

package/skills/legion-architect/SKILL.md

@@ -75,7 +75,10 @@ exercise a criterion end to end, building that path is a child issue of this tre
   the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string. A
   root session has `LEGION_TREE == LEGION_ISSUE`. The daemon establishes the sub-issue
   relationship from `parent`. Keep the returned issue keys in ordered waves; a child is
-  inert until released.
+  inert until released. Do not pass `assignee`: the default keeps the tree's questions in one
+  Inbox — under the shared token a child inherits its parent's assignee (the human who
+  answers the tree's asks); under a personal token it goes to that token's owner, whom
+  `dispatch_whoami` names. Set it only when a human told you a specific person owns that child.
 
 Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 Wave releases, child closures, and your own status are visible from the issue tree and the

package/skills/legion-controller/SKILL.md

@@ -107,6 +107,9 @@ override a Sami ruling quoted here.
 1. Read `legion state --json`, then inspect the reported Dispatch issue with `dispatch_read`.
    Verify the issue is in this project, is eligible for a root process, and whether it
    has pre-existing children. Dispatch and daemon state, not the wake text, decide triage.
+   Note the `Assignee:` line: that human answers the tree's asks, and their Inbox opens on
+   the issues they hold. Never reassign during triage — who holds an issue is the humans'
+   decision, made from the issue header.
 2. If it should run now, admit the root issue:
 
    ```text
@@ -123,6 +126,11 @@ override a Sami ruling quoted here.
    (or `icebox` for longer-term deferral). Dispatch status is the durable record;
    there is no separate marker to maintain. Do not triage a system-created child as a root
    issue.
+4. When you post a triage note (a `dispatch_comment` on the issue saying what you decided and
+   why), name who will be asked: `Assigned to <login>, who will get this tree's questions`,
+   or, when the `Assignee:` line says `unassigned`, `Unassigned — nobody's Inbox shows this
+   tree's questions until someone takes it from the issue header (Assignee, beside Priority)`.
+   An unassigned root still runs; the architect's asks wait in every Inbox's Unassigned band.
 
 ## Backlog eligibility